# Como corrigir a formatação de data do Date Field no ACF PRO

O formato de data errado no ACF date picker acontece quando o Return Format do Date Field não casa com o esperado no template: o ACF sempre salva a data como Ymd (20240101) no banco, então sem o Return Format certo a data sai invertida, em inglês ou como número cru.

## O que é formatação de data do Date Field no ACF PRO?

O ACF date picker (Date Field) é o campo do ACF PRO que guarda uma data escolhida em um calendário. Ele tem duas configurações de formato distintas que confundem a maioria dos casos: o Display Format, que define como a data aparece para quem seleciona no painel, e o Return Format, que define como a data volta quando você carrega o valor com get_field ou the_field no template. Segundo a documentação oficial do ACF, o valor é sempre salvo no banco no formato Ymd, ou seja, 20240101 para primeiro de janeiro de 2024, independente do que está configurado na tela.

O formato de data errado aparece quando o Return Format do campo não corresponde ao que o template espera mostrar. Se o Return Format está em Ymd, o get_field devolve a string crua 20240101 e a data sai como um número sem barras. Se o Return Format está em d/m/Y mas o desenvolvedor reformata por cima assumindo outro padrão, a data sai invertida, por exemplo mês e dia trocados. O problema é de configuração e de leitura do valor, não um defeito do plugin: o ACF entrega exatamente o formato que foi pedido no Return Format.

## Como identificar

- A data aparece no frontend como um número cru sem separadores, no estilo '20240101', em vez de uma data legível.
- A data sai invertida no template: o dia aparece no lugar do mês, como '01/03/2024' virando '03/01/2024'.
- O nome do mês aparece em inglês, como 'January', mesmo com o site em português.
- A data exibida no painel do ACF está correta, mas a mesma data sai diferente no frontend do site.
- Ao usar var_dump no retorno do get_field, o valor vem como a string '20240101' e não como uma data formatada.

**Antes de começar:** Antes de alterar o Return Format de um campo em produção, teste primeiro em staging: mudar o Return Format afeta todos os templates que leem o campo, e um template que reformatava a saída antiga pode passar a exibir a data errada. Faça backup do banco para poder reverter.

## Como prevenir

- Defina o Return Format do Date Field já na criação do campo, alinhado ao formato que o template vai exibir, para evitar reformatação manual depois.
- Padronize o uso de Ymd como Return Format quando o template precisar de formatos variados, e reconstrua a data com DateTime::createFromFormat a partir de Ymd.
- Nunca reformate a data partindo de um formato adivinhado: o valor no banco é sempre Ymd, então use esse formato como origem em qualquer conversão.
- Use date_i18n ou wp_date em vez de date() sempre que o nome do mês ou do dia da semana precisar aparecer no idioma do site.

Erros relacionados

- [Como corrigir Custom Fields que não aparecem no frontend no ACF PRO](https://full.services/wp-fixer/corrigir-custom-fields-frontend-acf-pro/)
- [Como corrigir o Repeater Field que não salva dados no ACF PRO](https://full.services/wp-fixer/corrigir-repeater-nao-salva-acf-pro/)
- [Como corrigir a Conditional Logic que não funciona no ACF PRO](https://full.services/wp-fixer/corrigir-conditional-logic-acf-pro/)

## Causa

- O Return Format do Date Field está configurado como Ymd, então o get_field devolve a string crua salva no banco (20240101) sem nenhum separador, e a data sai como número no template.
- O template reformata a data com date() ou DateTime usando o formato de entrada errado, ignorando que o ACF sempre salva no banco em Ymd, o que troca dia por mês ao interpretar a string.
- O Display Format e o Return Format foram confundidos: o desenvolvedor ajustou só o Display Format (que afeta o painel) esperando mudar a saída do template, que depende exclusivamente do Return Format.
- O the_field é usado direto no template e imprime o valor no Return Format atual sem reformatação, então qualquer formato diferente do desejado aparece exatamente como está configurado.
- A formatação usa funções de data do PHP que retornam o mês em inglês porque o locale do WordPress não foi aplicado, em vez de usar date_i18n ou wp_date para respeitar o idioma do site.

## Como resolver

1. Confira o Return Format do Date Field no grupo de campos: Em ACF, abra o grupo de campos, edite o Date Field e localize a configuração Return Format. É ela, e não o Display Format, que define como a data volta no get_field e no the_field. Ajuste para o formato que o template precisa exibir, por exemplo d/m/Y para o padrão brasileiro.

```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo do campo de data
Edite o campo do tipo Date Picker
Em Return Format, escolha o formato desejado (ex.: d/m/Y) e salve o grupo
```

2. Entenda que a data é sempre salva como Ymd no banco: A documentação oficial do ACF deixa claro que o valor do Date Field é sempre gravado no banco no formato Ymd (20240101), independente do Display Format e do Return Format. Qualquer reformatação manual no PHP precisa partir desse formato de origem, nunca de um formato adivinhado.

```
Formato de armazenamento no banco: Ymd (ex.: 20240101 para 01/01/2024)
Use sempre Ymd como formato de entrada ao reconstruir a data no PHP
```

3. Reformate a data no template a partir do formato Ymd: Quando precisar de um formato específico que o Return Format não cobre, defina o Return Format como Ymd para ter a string crua e reconstrua a data com DateTime::createFromFormat usando Ymd como formato de origem. Assim o dia e o mês nunca são trocados.

```
Defina o Return Format do campo como Ymd
No template, recupere com $valor = get_field('data')
$data = DateTime::createFromFormat('Ymd', $valor)
echo $data->format('d/m/Y')
```

4. Garanta o mês em português com date_i18n ou wp_date: Se a data precisa do nome do mês ou do dia da semana em português, não use a função date() crua do PHP, que ignora o idioma do WordPress. Use date_i18n ou wp_date passando o timestamp da data para respeitar o locale configurado no site.

```
$data = DateTime::createFromFormat('Ymd', get_field('data'))
echo date_i18n('d de F de Y', $data->getTimestamp())
```

5. Confirme o Display Format só para a experiência no painel: Depois de acertar a saída do template, ajuste o Display Format apenas para deixar o calendário do painel legível para quem edita. Ele não afeta o frontend, então serve só para a usabilidade interna ao selecionar a data.

```
Painel WP -> ACF -> Grupos de Campos -> edite o Date Field
Defina o Display Format (ex.: d/m/Y) e salve
Abra um post para conferir o calendário no painel
```


## Código

```php
<?php
// Return Format do campo definido como Ymd para ter a string crua.
$valor = get_field( 'data_do_evento' );

if ( $valor ) {
    // O ACF salva sempre em Ymd (ex.: 20240101); use Ymd como origem.
    $data = DateTime::createFromFormat( 'Ymd', $valor );

    if ( $data ) {
        // Formato numérico simples, sem troca de dia/mes.
        echo esc_html( $data->format( 'd/m/Y' ) );

        // Mes por extenso no idioma do site (pt_BR).
        echo esc_html( date_i18n( 'd de F de Y', $data->getTimestamp() ) );
    }
}
```

## Perguntas frequentes

### Por que o ACF date picker retorna a data como número 20240101

Porque o Return Format do campo está configurado como Ymd, que é o mesmo formato em que o ACF sempre salva a data no banco. O get_field devolve essa string crua sem separadores. Mude o Return Format para d/m/Y, ou reconstrua a data no template com DateTime::createFromFormat a partir de Ymd.

### Qual a diferença entre Display Format e Return Format no Date Field

O Display Format define como a data aparece no calendário do painel, para quem seleciona a data. O Return Format define como a data volta no template ao usar get_field ou the_field. Para corrigir a saída no frontend, ajuste o Return Format, pois o Display Format não afeta o site.

### Em que formato o ACF salva a data no banco de dados

Segundo a documentação oficial do ACF, o valor do Date Field é sempre salvo no banco no formato Ymd, ou seja, YYYYMMDD, como 20240101 para primeiro de janeiro de 2024. Esse formato é fixo e independe do Display Format e do Return Format escolhidos.

### Por que a data do ACF aparece com dia e mês trocados

Isso ocorre quando o template reformata a data partindo de um formato de entrada errado. Como o ACF salva sempre em Ymd, qualquer conversão precisa usar Ymd como formato de origem no DateTime::createFromFormat. Adivinhar outro formato faz o PHP interpretar o dia como mês.

### Como deixar o mês da data do ACF em português

Não use a função date() crua do PHP, que retorna o mês em inglês. Reconstrua a data com DateTime::createFromFormat usando Ymd e exiba com date_i18n ou wp_date, que respeitam o idioma configurado no WordPress e mostram o mês em português.

### Mudar o Return Format altera as datas já salvas

Não. O valor no banco continua sempre em Ymd, então datas antigas não são reescritas. O Return Format só muda como o valor é entregue ao ser lido. Por isso a mudança é segura para os dados, mas pode afetar templates que reformatavam a saída antiga.

### Devo usar get_field ou the_field para a data

Use get_field quando precisar tratar ou reformatar a data antes de exibir, pois ele retorna o valor para você manipular. O the_field imprime direto no Return Format atual, sem chance de reformatação, então só serve quando o Return Format já está no formato final desejado.

**Fonte:** [Advanced Custom Fields — Date Picker field](https://www.advancedcustomfields.com/resources/date-picker/)