FOX

No modo em que o cliente paga na moeda selecionada, raw_woocommerce_price() é ligado a woocommerce_product_get_price, aos getters de preço normal e promocional e aos getters de variações. Correr com 9999 coloca-o depois de outros plugins que ajustam o preço base. No modo apenas de apresentação, só o filtro raw_woocommerce_price é usado, pelo que os montantes guardados do carrinho e das encomendas ficam na moeda base.

Casos limite tratados no conversor: os preços vazios passam sem alteração, um produto variável pai consultado com display=false é ignorado para evitar converter duas vezes o mín./máx., e o getter do preço promocional devolve uma string vazia quando não há preço promocional guardado. Sem isso, um preço promocional vazio convertido passa a 0 e o WooCommerce mostra um preço riscado.

O WooCommerce guarda os arrays de preços calculados de um produto variável num transient indexado por um hash dos dados de preço. Se a moeda não fizer parte desse hash, os preços convertidos do primeiro visitante são servidos a todos. woocommerce_get_variation_prices_hash() acrescenta a moeda atual.

woocommerce_variation_prices() converte depois cada entrada, aplica os preços fixos por variação e reordena cada array com asort(). O intervalo de preços é lido do primeiro e do último elemento, e os preços fixos por moeda podem alterar a ordem das variações em relação à moeda base.

Os preços fixos são guardados como meta do produto por campo e moeda (_woocs_regular_price_EUR, _woocs_sale_price_EUR), com -1 a significar 'não definido, usar a taxa'. Um preço fixo na moeda do visitante é usado tal como está. Caso contrário, um preço por país substitui o preço base, e o resultado é convertido pela taxa. Os preços por país agrupam países em blocos com um preço por bloco, e o país do visitante vem da geolocalização do WooCommerce guardada no estado do visitante.

Os preços por perfil são aplicados depois desse passo. Quando há um preço definido para o perfil do utilizador, este substitui o preço escolhido até então, incluindo um preço fixo numa moeda, e é convertido pela taxa.

Quando um preço promocional por país é deixado vazio, get_product_geo_data() copia para ele o preço normal; caso contrário o produto ficaria gratuito nesse país. Quando um campo fixo de promoção está vazio, a consulta recorre ao campo fixo de preço normal.

Os preços fixos são guardados por campo, mas woocommerce_product_get_price passa apenas um número. get_price_type() compara o valor recebido com os preços normal e promocional em bruto do produto, lidos em contexto 'edit'. Se nenhum corresponder, mantém um mapa estático do primeiro preço visto para cada produto no pedido e trata um valor posterior e maior como o preço normal.

Isto é uma heurística, pelo que os tipos de campo explícitos são passados sempre que quem chama os conhece. Os preços por perfil usam a sua própria cópia da mesma lógica.

A lista de preços opcional sob um produto é construída dentro de woocommerce_price_html(). Para cada moeda, a moeda atual é trocada, o valor é formatado com os decimais e separadores dessa moeda, e a moeda original é restaurada no fim.

O intervalo de um produto variável não pode ser calculado como mín./máx. base vezes a taxa, porque as variações individuais podem ter preços fixos. _get_min_max_variation_prices() recalcula o preço de cada variação para a moeda de destino e descarta os valores zero. Os produtos agrupados percorrem os seus filhos e tratam os filhos variáveis da mesma forma.

woocs_skip_conversion é verificado primeiro no conversor: uma integração que já fixou o preço de um artigo na moeda ativa devolve true e o montante passa sem alteração. O indicador de pedido woocs_block_price_hook desliga a conversão para uma secção de código, usado por exemplo enquanto os payloads de webhooks são construídos.

Para o sentido oposto, woocs_convert_price e woocs_back_convert_price permitem que plugins de terceiros convertam os seus próprios montantes na moeda base, e convert_from_to_currency() converte entre quaisquer duas moedas da loja através da base: value / rate_from * rate_to.

O WooCommerce lê o número de decimais de uma única opção. O FOX responde a essa opção com a definição da moeda atual, e o conversor arredonda com number_format() para a mesma precisão, de modo que o valor guardado no carrinho e o valor apresentado coincidam.

JPY e TWD estão fixados no código como moedas sem cêntimos, o administrador pode acrescentar mais, e o filtro woocs_precision_on_calc permite a um site substituir a precisão por moeda.

As tarifas de envio são calculadas na moeda base e convertidas mais tarde em woocommerce_package_rates. Se fossem primeiro arredondadas aos decimais da moeda do visitante (por exemplo 0 para JPY), o valor base perderia precisão antes da conversão. woocs_fix_decimals() devolve os decimais base quando add_rate está na pilha de chamadas.

O mesmo se aplica aos arrays de preços de variações: woocs_fix_variation_decimal() formata-os com os decimais base antes de o conversor passar por eles.

Os separadores decimal e de milhares são filtrados por moeda (seis esquemas em get_decimal_sep() e get_thousand_sep()). No editor de encomendas do wp-admin, os campos de entrada do WooCommerce, a sua validação JS e wc_format_decimal() assumem todos o separador da loja, pelo que um separador decimal com vírgula alteraria os montantes guardados. Os separadores por moeda ficam por isso desligados no editor de encomendas.

woocs_is_admin_order_edit_context() reconhece as ações AJAX do editor de encomendas pelo nome, as outras chamadas AJAX pelo referer (página wc-orders, tipo de post shop_order, ID do post da encomenda) e os ecrãs HPOS e legado. A parte do pedido fica em cache numa variável estática; a verificação do ecrã é reavaliada porque get_current_screen() está vazio no início do pedido. Os montantes de reembolso escritos com vírgula são normalizados antes de o WooCommerce os validar.

apply_conversion() corre em woocommerce_paypal_args e reformata todos os campos amount_* e tax_cart com 0 decimais quando a moeda atual não tem cêntimos. enable_custom_currency() alarga a lista de moedas permitidas do PayPal no WooCommerce para que o gateway continue disponível quando o visitante paga numa moeda que não é a base.

Uma taxa como moedas por USD pode ser muito inferior a 0.0001, e a conversão de float para string do PHP dá notação exponencial que o formulário de administração e o e-mail de taxas não conseguem usar. rate_to_string() calcula o número de decimais a partir de log10 do valor, limita-o a 20 e remove os zeros finais.

WOOCS_STORAGE expõe set_val/get_val/is_isset e escolhe o backend configurado. O armazenamento em transient é indexado por um hash do IP do cliente, com preferência por CF-Connecting-IP atrás da Cloudflare, porque a Cloudflare substitui qualquer valor fornecido pelo cliente. Memcached e Redis também são suportados.

WOOCS_SESSION reutiliza a tabela woocommerce_sessions com um cookie assinado por HMAC, lê através da cache de objetos e só escreve no shutdown quando os dados mudaram.

Com o armazenamento em transient e o modo de cache ativos, front.js cria uma vez um ID aleatório (crypto.randomUUID quando disponível) e envia-o com cada pedido. O servidor sanitiza-o com sanitize_key() e calcula o seu hash para a chave do transient, pelo que utilizadores de NAT de escritório ou de operadoras móveis ficam em compartimentos separados. O ID é gerado em minúsculas de propósito: sanitize_key() converte para minúsculas, e um ID com maiúsculas e minúsculas daria um hash para outro compartimento.

Neste modo, o transient vive 30 dias em vez de 1, porque a chave é estável por navegador. Se o localStorage estiver bloqueado, o código recorre em silêncio à chave por IP.

Os pedidos jQuery recebem a chave através de um handler ajaxSend, mas o WooCommerce Blocks, a Store API e o PayPal Payments usam fetch() e começam antes de o DOM estar pronto. O wrapper é instalado ao nível superior. A chave vai num cabeçalho X-WOOCS-SK, e não num argumento de query, porque um argumento de query por visitante dividiria a cache de página por visitante. As chamadas entre domínios são deixadas em paz, uma vez que um cabeçalho personalizado dispara um preflight CORS que pode quebrar os SDKs de pagamento.

Do lado do PHP, os pedidos wp-json para as rotas de carrinho, loja e batch mantêm o plugin carregado, para que o carrinho e o checkout por blocos sejam apresentados na moeda do visitante.

woocommerce_price_html() envolve cada preço num span com o ID do produto e um ID de redesenho único. Numa página em cache, front.js recolhe os marcadores e envia-os para woocs_get_products_price_html; o JSON das variações no formulário de adicionar ao carrinho e os shortcodes de preços personalizados são atualizados da mesma forma. Um estilo de preloader pode esconder os preços desatualizados até a resposta chegar.

O servidor devolve uma resposta vazia quando a moeda em que a página em cache foi apresentada já é igual à guardada do visitante, pelo que essa visualização de página não custa nenhuma apresentação. Só apresenta get_price_html() para produtos publicados e visíveis.

O WooCommerce guarda os fragmentos do carrinho em sessionStorage indexados pelo hash do carrinho, e o hash depende apenas do conteúdo do carrinho. O FOX filtra woocommerce_cart_hash para md5(carrinho + moeda), de modo que uma mudança invalida os fragmentos guardados e o envio é recalculado.

Quando a moeda chega no URL numa página em cache, front.js começa por a espelhar no compartimento da chave do navegador e só depois dispara wc_fragment_refresh; caso contrário, a atualização leria um compartimento vazio e recorreria à moeda base.

set_currency() guarda apenas moedas ativadas, e o valor guardado é verificado de novo em cada pedido, pelo que uma moeda removida pelo administrador volta à base. get_woocommerce_currency() nunca devolve um código desconhecido ao WooCommerce, porque o WooCommerce o gravaria na encomenda.

As moedas marcadas como privadas não podem ser selecionadas através de ?currency= nem do seletor AJAX. O valor de pedido woocs_in_order_currency só aceita uma moeda privada para utilizadores com edit_shop_orders.

woocommerce_package_rates() multiplica o custo e cada entrada de imposto pela taxa e arredonda aos decimais da moeda. Um custo fixo de tarifa única por moeda é guardado na própria opção de definições da instância do método de envio. Quando se usa um custo fixo, escalar o imposto antigo estaria errado, pelo que o imposto é recalculado com WC_Tax::calc_shipping_tax().

Um custo de tarifa única como '[cost] * 0.1' recebe o custo do carrinho na moeda do visitante, e a tarifa de envio resultante é depois convertida de novo em woocommerce_package_rates. woocommerce_fix_shipping_calc() divide primeiro o argumento do custo pela taxa, de modo que a conversão acontece uma só vez.

O método de envio gratuito compara o subtotal apresentado com min_amount. Quando o cliente paga na moeda selecionada, o subtotal do carrinho está nessa moeda, pelo que a verificação é reimplementada: o subtotal é convertido de volta com a taxa atual, o desconto e o imposto do desconto são também convertidos de volta, as definições ignore_discounts e de apresentação de impostos são respeitadas, e os requisitos de cupão/qualquer/ambos são avaliados como no WooCommerce.

Se estiver definido um mínimo fixo por moeda, também ele é convertido de volta, de modo que os dois lados da comparação ficam na moeda base.

woocommerce_coupon_loaded() converte o montante do cupão (não para os tipos percent e percent_product) e o gasto mínimo e máximo, e grava-os de volta com os setters do cupão, de modo que toda a validação do WooCommerce corre numa só moeda. Os montantes e limites fixos de cupões por moeda, guardados como meta do cupão, substituem os valores convertidos.

No modo apenas de apresentação, a moeda é reposta na base na página de checkout, em checkout_process, no checkout por blocos e nas atualizações da revisão da encomenda. No modo de pagamento na moeda selecionada, o pedido de checkout lê a moeda guardada de forma explícita e, opcionalmente, a moeda é imposta pelo país do visitante. Uma encomenda pendente paga mais tarde a partir do seu link de pagamento é passada para a moeda da própria encomenda.

Os gateways de pagamento podem ser escondidos ou mostrados por moeda, uma vez que muitos gateways suportam apenas algumas moedas.

RateProvider::getRate() constrói o URL, obtém com um timeout e delega em parseResponse(). Os feeds dos bancos centrais são cotados em relação à sua própria moeda, pelo que os analisadores calculam taxas cruzadas: o BCE tem base EUR, e o feed do Banco da Rússia traz também um Nominal (taxa por 10 ou 100 unidades) que tem de ser dividido.

get_rate_provider() faz corresponder o nome da fonte configurada a um ficheiro de classe. Os sites podem acrescentar as suas próprias fontes através dos filtros woocs_add_custom_rate e woocs_add_aggregator_processor.

A fonte Pulse Verity devolve um preço em USD para qualquer símbolo, pelo que um código de moeda fiduciária receberia em silêncio o preço de um token sem relação. O fornecedor verifica primeiro uma lista ISO 4217 fixada no código, porque os plugins de pagamento em criptomoedas acrescentam moedas à lista de moedas do WooCommerce e essa lista não é de confiança. Funciona apenas com base USD, envia a chave da API como cabeçalho Bearer, reporta o próprio código de erro da API para qualquer resposta que não seja 2xx (chave errada, restrição do plano, limite de pedidos) e rejeita preços zero ou não numéricos. O preço em USD por moeda devolvido é invertido em moedas por 1 USD.

PN_WP_CRON_WOOCS guarda o início, a próxima execução, o intervalo e a última execução por hook numa só opção e é verificado a partir de init, admin_init e rest_api_init. Como é chamado em todos os pedidos, attach() tem de ser idempotente: com um intervalo inalterado, deixa next intacto, e numa mudança de intervalo recalcula next a partir da última execução, limitado a agora mais um intervalo. Os três hooks são registados com 0 argumentos aceites, porque rest_api_init passa o objeto WP_REST_Server, que de outro modo cairia no parâmetro $reset e reiniciaria o agendamento em cada pedido REST.

process() avança a próxima execução antes de chamar o hook, apanha e regista as exceções que este lança, e executa cada hook no máximo uma vez por pedido. O agendamento atualizado é guardado na opção depois de os hooks terem corrido.

rate_auto_update() obtém cada moeda no seu próprio bloco try e só substitui uma taxa por um número positivo, pelo que uma moeda ou fonte que falha não impede as outras e nunca grava zero nem um texto de erro como taxa. get_rate() passa todas as taxas numéricas por ExchangeRateLimiter, que as limita a um mínimo e um máximo opcionais por moeda. Depois de guardar, a ação woocs_sheduler_rates_updated permite que outro código reaja.

Todas as taxas são guardadas como unidades por 1 base, pelo que uma nova base torna todos os números errados de uma só vez. save_etalon() guarda o novo indicador de base, muda default_currency em memória e chama get_rate() para todas as outras moedas antes de responder ao ecrã de administração, de modo que o formulário é preenchido de novo com valores consistentes.

A margem é guardada junto à taxa como montante fixo ou percentagem e aplicada num filtro woocs_currency_data_manipulation com prioridade 1, de modo que todos os consumidores de get_currencies() veem a taxa com margem. get_currencies(true) ignora os filtros quando é preciso o valor bruto.

No checkout e na página de agradecimento, a taxa, a moeda base e um marcador de 'alterado manualmente' são escritos com $order->update_meta_data(), que funciona tanto com HPOS como com armazenamento em posts. Se a moeda atual não estiver na lista, é usada a taxa base. As chaves meta ficam escondidas na apresentação dos itens. Um administrador pode corrigir a taxa guardada a partir do ecrã da encomenda, e as linhas de análise de produtos da encomenda são ressincronizadas.

O recálculo converte os totais da encomenda, os subtotais e totais das linhas, os arrays de impostos por taxa, os itens de envio e os respetivos impostos, os itens de imposto e os reembolsos. Em HPOS passa pelos setters CRUD, converte também as linhas de taxas e de cupões e recalcula os impostos. No armazenamento legado, atualiza diretamente o post meta e o meta dos itens da encomenda, incluindo o desconto do carrinho da encomenda.

Se um site definir woocs_order_recalculated_custom(), esta é chamada antes de guardar, com a encomenda, ambas as moedas e a taxa antiga, para montantes que têm de manter um valor fixo por moeda. Uma ação em massa recalcula todas as encomendas para a moeda base.

A moeda atual pertence a quem desencadeou o pedido: um administrador a concluir uma encomenda, uma tarefa cron ou um cliente a navegar noutra moeda. O FOX passa para a moeda da encomenda em wc_get_template para os templates de e-mail, na notificação de concluída e no reenvio de e-mails, na geração de faturas em PDF, nas listas e vistas de encomendas de Minha Conta, na pré-visualização de encomendas na administração e, por linha da lista de encomendas HPOS, através do filtro do nome do comprador.

O WooCommerce Analytics copia os montantes das encomendas tal como estão para as suas próprias tabelas de consulta, pelo que a receita misturaria moedas. WOOCS_analytics liga-se a woocommerce_analytics_update_product, _tax e _coupon, lê a linha que o WooCommerce acabou de escrever, divide cada montante pela taxa guardada da encomenda (ou pela taxa atual, se não existir) e arredonda aos decimais base. Os relatórios legados do WooCommerce são adaptados da mesma forma, convertendo de volta cada encomenda.

O wp-admin corre normalmente na moeda base. Para as ações AJAX do editor de encomendas (adicionar item, guardar itens, recalcular impostos), a moeda atual é definida como a da encomenda, para utilizadores que podem editar encomendas. Quando um produto com preço fixo nessa moeda é adicionado manualmente, o subtotal e o total do item são definidos a partir do preço fixo e os totais da encomenda são recalculados. Quando um cupão é adicionado no editor, a moeda atual é passada para a da encomenda.

Os sistemas POS e ERP sincronizam preços através da API REST do WooCommerce, e um pedido pode trazer a sessão de um visitante que selecionou outra moeda. A variável de servidor SCRIPT_URI usada pela proteção REST geral existe no Apache mas não no nginx, pelo que a rota é também interpretada a partir de REQUEST_URI usando rest_get_url_prefix(), ou de ?rest_route=, e o plugin retorna antes de o seu objeto ser criado para qualquer rota wc/vN. A Store API e o próprio espaço de nomes do FOX não são afetados.

woocs_validate_currency() responde com a moeda da loja quando o objeto do plugin não existe no pedido. Edição premium.

A entrega assíncrona corre através do Action Scheduler: a moeda base é ativada com prioridade 1 de woocommerce_deliver_webhook_async e desativada com 999. A entrega síncrona é mais difícil: desde o WooCommerce 4.4 os webhooks são colocados em fila e entregues no shutdown, pelo que o FOX ativa a moeda base dentro do filtro woocommerce_webhook_deliver_async apenas quando este é chamado no shutdown com um WC_Webhook e async=false, e desativa-a em woocommerce_webhook_payload, logo a seguir a build_payload().

A entrega pode correr num pedido que traz os cookies de um visitante e, portanto, a moeda desse visitante. Tanto o indicador de conversão como current_currency são alterados, porque os preços fixos por moeda leem current_currency diretamente. Edição premium.

Os crawlers podem chegar com uma moeda no URL. Os user agents de bots conhecidos são repostos na moeda base em wp_head, a menos que o administrador o desative. Em paralelo, structured_data_product_offer() define priceCurrency como a base e divide as entradas price, lowPrice, highPrice e priceSpecification pela taxa, de modo que a marcação do produto se mantém consistente com a moeda da loja.

A exportação CSV de produtos repõe a moeda antes da sua consulta, de modo que os preços exportados são valores base que podem ser importados de volta. O carregamento de variações no editor de produtos e todas as páginas do wp-admin que não sejam AJAX correm na moeda base. O plugin não carrega para as ações AJAX do editor em massa BEAR, para o carregamento de itens de encomenda, para pedidos REST cujo URL contém /refunds ou paypal (PayPal Payments), nem para reembolsos no backend, a menos que um plugin conhecido o precise, porque esses pedidos escrevem montantes guardados.

woocs/v3 expõe a lista de moedas, o preço de um produto e um lote de preços de produtos. O callback só define a moeda pedida se esta existir na loja, calcula os preços com a mesma precedência do conversor principal (fixo, país, perfil, depois taxa), devolve valores em bruto por variação com mínimo e máximo ou HTML, e restaura a moeda anterior.

A moeda base da loja era AUD. Durante o pedido de importação, o GeoIP tinha mudado a moeda atual para USD, e o importador gravava a moeda atual em cada encomenda. Foi acrescentada uma chamada a $WOOCS->reset_currency(), protegida por class_exists('WOOCS'), em dois pontos do código de encomendas do importador, de modo que as encomendas são escritas na moeda base. Trata-se de um patch ao importador de terceiros, que tem de ser reaplicado após uma atualização desse plugin. O cliente confirmou que funcionou.