Hyvä Checkout explicado: Magewire, customização e pagamentos

O checkout é a parte de um projeto Hyvä que exige uma decisão separada. O tema Hyvä substitui a stack de JavaScript da storefront, mas o checkout padrão do Magento é uma aplicação grande em Knockout e UI components que não roda no Hyvä. Então toda loja Hyvä acaba com uma de poucas opções para o checkout. Este artigo explica o Hyvä Checkout do ponto de vista do desenvolvedor: como ele é construído, como se customiza, o que significa para integrações de pagamento e como se compara a manter o checkout Luma.

Opções de checkout em uma loja Hyvä

Há três caminhos realistas:

1. Fallback para o checkout Luma. A storefront roda no Hyvä e as rotas do checkout são renderizadas com um tema baseado em Luma. Funciona com todo módulo de pagamento que suporta o checkout padrão. O custo é que o checkout carrega a stack completa de RequireJS e Knockout, e você mantém estilos em dois temas.
2. Hyvä Checkout. Um produto separado da equipe do Hyvä, feito para temas Hyvä. Veja em hyva.io o licenciamento e o preço atuais.
3. Um checkout de terceiros ou custom. Existem outras extensões de checkout com suporte a Hyvä, e um checkout totalmente custom é possível em cima de GraphQL ou da REST API. É o caminho mais caro para construir e manter.

O fallback é como a maioria das migrações começa, porque desacopla o lançamento do tema do trabalho no checkout. Os trade-offs mais amplos estão em Hyvä vs Luma para desenvolvedores.

Como o Hyvä Checkout é construído

O Hyvä Checkout é renderizado no servidor. Ele é construído sobre o Magewire, uma adaptação para o Magento da ideia do Laravel Livewire. Em vez de uma aplicação JavaScript que chama endpoints REST, cada parte do checkout é um componente PHP com propriedades e métodos públicos. O template liga os campos do formulário a essas propriedades. Quando o usuário muda um campo, o Magewire manda um pequeno request ao servidor, o componente PHP roda e o servidor devolve o HTML atualizado daquele componente.

Para um desenvolvedor Magento isso tem um grande efeito prático. A maior parte da customização do checkout é escrita em PHP e phtml, com o layout XML decidindo onde as coisas ficam. Você não precisa aprender o checkout em UI components e Knockout, e não precisa escrever mixins para arquivos Magento_Checkout/js/model/*.

O trade-off é que as interações vão ao servidor. Cada mudança de campo ligada ao vivo gera um request. O desenho dos componentes importa: ligue os campos para atualizar no change ou no submit em vez de a cada tecla, a menos que você realmente precise de atualização ao vivo.

Configuração do checkout e steps

O Hyvä Checkout permite definir checkouts e seus steps em arquivos de configuração chamados hyva_checkout.xml. Um step corresponde a layout handles, o que significa que o conteúdo de cada step é controlado com layout XML normal. Layouts de um step e de vários steps são possíveis, e o admin da loja pode escolher qual checkout usar na seção de configuração do Hyvä Checkout. Leia os arquivos hyva_checkout.xml no próprio pacote do Hyvä Checkout para ver os nomes dos steps e os layout handles da sua versão antes de começar a adicionar blocks.

Adicionando um campo custom com Magewire

Um pedido típico: adicionar um campo de observação de entrega no step de envio e salvá-lo no quote. No checkout Luma isso significa um UI component, um mixin JavaScript no shipping save processor, um extension attribute e um plugin. Esse fluxo está descrito em adicionando um campo custom ao checkout do Magento 2. No Hyvä Checkout é um componente Magewire e um template.

Primeiro, o componente. Ele carrega o valor atual ao montar e salva o quote quando a propriedade é atualizada.

<?php
declare(strict_types=1);

namespace Acme\Checkout\Magewire;

use Magento\Checkout\Model\Session as CheckoutSession;
use Magento\Quote\Api\CartRepositoryInterface;
use Magewirephp\Magewire\Component;

class DeliveryNote extends Component
{
    public string $note = '';

    public function __construct(
        private readonly CheckoutSession $checkoutSession,
        private readonly CartRepositoryInterface $cartRepository
    ) {
    }

    public function mount(): void
    {
        $quote = $this->checkoutSession->getQuote();
        $this->note = (string) $quote->getData('acme_delivery_note');
    }

    public function updatedNote(string $value): string
    {
        $value = mb_substr(trim($value), 0, 255);
        $quote = $this->checkoutSession->getQuote();
        $quote->setData('acme_delivery_note', $value);
        $this->cartRepository->save($quote);

        return $value;
    }
}

O método updatedNote segue a convenção de nomes do Livewire: updated mais o nome da propriedade. Ele roda depois que a propriedade muda e seu valor de retorno vira o novo valor da propriedade. A coluna acme_delivery_note é adicionada à tabela quote e à tabela sales_order com declarative schema, e copiada do quote para o pedido com um fieldset ou um observer, igual a qualquer checkout.

O template liga um input à propriedade:

<?php
/** @var \Magento\Framework\Escaper $escaper */
/** @var \Acme\Checkout\Magewire\DeliveryNote $magewire */
?>
<div class="my-4">
    <label for="acme-delivery-note" class="block font-semibold">
        <?= $escaper->escapeHtml(__('Delivery note')) ?>
    </label>
    <textarea id="acme-delivery-note"
              class="form-textarea w-full"
              maxlength="255"
              wire:model.lazy="note"></textarea>
</div>

O wire:model.lazy sincroniza o valor quando o campo perde o foco, não a cada tecla. Por fim, o layout XML adiciona o block com o componente anexado pelo argumento magewire. Coloque dentro do container do step onde você quer o campo, usando o layout handle daquele step.

<block name="checkout.acme.delivery-note"
       template="Acme_Checkout::checkout/delivery-note.phtml">
    <arguments>
        <argument name="magewire" xsi:type="object">Acme\Checkout\Magewire\DeliveryNote</argument>
    </arguments>
</block>

Essa é a feature inteira no frontend. Nenhum JavaScript foi escrito.

Validação antes de avançar

Muitas vezes os componentes precisam impedir que o cliente continue até que algo seja válido, por exemplo uma data de entrega obrigatória. O Hyvä Checkout tem um mecanismo de avaliação para isso: o componente informa se está completo, e o checkout bloqueia a navegação ou a finalização do pedido e mostra a mensagem se não estiver. Use isso em vez de esconder o botão de finalizar com JavaScript, porque mantém a regra no servidor.

Métodos de pagamento

Esta é a parte a verificar primeiro em qualquer projeto. Um módulo de pagamento feito para o checkout Luma não funciona automaticamente no Hyvä Checkout. Ele precisa de uma integração com o Hyvä Checkout, que normalmente é um componente Magewire para o formulário de pagamento mais o JavaScript que o SDK do provedor exigir.

• Muitos provedores de pagamento agora publicam integrações com o Hyvä Checkout. Pergunte ao provedor, confira as informações de compatibilidade do Hyvä e confirme que a integração suporta os recursos que você usa (3D Secure, wallets, cartões salvos, reembolsos pelo admin).
• Métodos offline como cheque ou money order e transferência bancária funcionam com pouco ou nenhum código extra.
• Se o seu provedor não tem integração, construir uma dá trabalho de verdade. Orce como uma tarefa própria e teste com o sandbox do provedor, incluindo os casos de falha.

O mesmo vale para métodos de envio que renderizam UI custom no checkout (seletores de ponto de retirada, seletores de data de entrega). Transportadoras que só retornam tarifas funcionam como estão, porque a coleta de tarifas é código de backend. Qualquer coisa com widget de frontend custom precisa de uma versão para o Hyvä Checkout.

Hyvä Checkout vs fallback Luma

Tópico	Hyvä Checkout	Fallback Luma
Stack de frontend	Magewire, Alpine.js, Tailwind	RequireJS, Knockout, UI components, LESS
Customização	Componentes PHP e layout XML	Componentes JS, mixins, layout XML do checkout
Módulos de pagamento	Precisam de uma integração com o Hyvä Checkout	Funcionam como no Luma
Estilização	Mesmo tema Tailwind da loja	Tema Luma separado para manter
Licenciamento	Produto separado, veja hyva.io	Sem produto extra

Planejando a mudança de checkout

1. Liste todos os métodos de pagamento, métodos de envio com widget custom e extensões de checkout em uso.
2. Verifique o suporte de cada um ao Hyvä Checkout. O que estiver faltando vira tarefa de desenvolvimento ou motivo para adiar.
3. Liste toda customização que já existe no checkout Luma (campos custom, steps, validações). Cada uma precisa ser refeita como um componente Magewire.
4. Decida se vai lançar o tema Hyvä com o fallback do checkout Luma e mover o checkout depois. Essa costuma ser a ordem de menor risco.
5. Teste a finalização do pedido de ponta a ponta em staging com todos os métodos de pagamento, como visitante e logado, com cupons e com um carrinho misto.

Se a loja hoje tem muita lógica custom no checkout, a mudança para o Hyvä Checkout costuma ser um bom momento para simplificar. Muito código do checkout Luma existe para contornar o modelo de JavaScript e desaparece quando a lógica passa para o PHP.

FAQ

O Hyvä Checkout vem incluído no tema Hyvä?

É um produto separado. O licenciamento mudou ao longo do tempo, então confira o hyva.io para os termos atuais.

Posso lançar uma loja Hyvä com o checkout padrão do Magento?

Sim. Um fallback para o checkout Luma renderiza as rotas do checkout com um tema baseado em Luma enquanto o resto da loja usa Hyvä.

O que é o Magewire?

Uma adaptação para o Magento da abordagem do Laravel Livewire. Os componentes são classes PHP com propriedades públicas ligadas aos templates, e as atualizações são renderizadas no servidor e trocadas na página.

O meu módulo de pagamento vai funcionar no Hyvä Checkout?

Só se ele tiver uma integração com o Hyvä Checkout. As partes de backend, como captura e reembolso, não mudam, mas o formulário de pagamento no checkout precisa de uma versão baseada em Magewire.

Atendo como freelancer em Magento e Hyvä Checkout. Se precisar de ajuda com isso, fale comigo.