{
  "id": "helper-datehelper",
  "title": "Helper — DateHelper",
  "description": "Formatação de datas e horários com timezone configurado na aplicação.",
  "type": "technical-reference",
  "status": "implemented",
  "visibility": "public",
  "tags": [
    "sge/helpers",
    "sge/formatacao",
    "sge/data"
  ],
  "related": [
    "helper-funcoes-globais",
    "providers"
  ],
  "sourceRefs": [
    "https://github.com/sge-suite/sge/blob/master/app/Helpers/DateHelper.php",
    "https://github.com/sge-suite/sge/blob/master/tests/Unit/Helpers/FormattingHelpersTest.php"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Responsabilidade\n\nClasse final para apresentação de `string|DateTimeInterface|null`. Toda data não nula passa por `Carbon::parse()` e é convertida para `config('app.timezone')`.\n\n| Método                  | Formato/resultado                                         |\n| ----------------------- | --------------------------------------------------------- |\n| `format()`              | `D de MMMM de YYYY`, por exemplo `10 de janeiro de 2024`. |\n| `formatShort()`         | `DD/MM/YYYY`.                                             |\n| `formatRelative()`      | `diffForHumans()`, relativo ao momento atual.             |\n| `formatDateTime()`      | `d/m/Y às H:i`.                                           |\n| `formatMonthYear()`     | `MM/YYYY`.                                                |\n| `formatMonthYearFull()` | `MMMM YYYY` com título em português.                      |\n| entrada `null`          | `-` em todos os métodos.                                  |\n\n## Cuidados\n\n- `formatRelative()` depende do relógio atual; testes devem congelar o tempo quando necessário.\n- O timezone é o da configuração da aplicação, não necessariamente o timezone da string de entrada.\n- `formatMonthYearFull()` usa `Str::title()` após `isoFormat()`.\n- Não usar o helper para cálculos de prazo do domínio; usar Carbon/serviço de regra e formatar apenas na saída.\n\n## Checklist\n\n- [x] Implementar os seis formatos.\n- [x] Tratar `null` com placeholder `-`.\n- [x] Aplicar timezone configurado.\n- [x] Expor funções correspondentes em `app/helpers.php`.\n- [x] Testar `DateTimeImmutable` e conversão de UTC para `America/Sao_Paulo`.\n- [ ] Adicionar testes para mês por extenso, relativo, entrada inválida e mudança de timezone.\n- [ ] Confirmar locale de `Carbon` em todos os ambientes.\n\n## Relacionamentos\n\n- [Funções globais](doc:helper-funcoes-globais)\n- [Providers](doc:providers)",
  "sections": [
    {
      "id": "responsabilidade",
      "level": 2,
      "title": "Responsabilidade",
      "text": "Classe final para apresentação de `string|DateTimeInterface|null`. Toda data não nula passa por `Carbon::parse()` e é convertida para `config('app.timezone')`.  | Método                  | Formato/resultado                                         | | ----------------------- | --------------------------------------------------------- | | `format()`              | `D de MMMM de YYYY`, por exemplo `10 de janeiro de 2024`. | | `formatShort()`         | `DD/MM/YYYY`.                                             | | `formatRelative()`      | `diffForHumans()`, relativo ao momento atual.             | | `formatDateTime()`      | `d/m/Y às H:i`.                                           | | `formatMonthYear()`     | `MM/YYYY`.                                                | | `formatMonthYearFull()` | `MMMM YYYY` com título em português.                      | | entrada `null`          | `-` em todos os métodos.                                  |",
      "line": 1
    },
    {
      "id": "cuidados",
      "level": 2,
      "title": "Cuidados",
      "text": "- `formatRelative()` depende do relógio atual; testes devem congelar o tempo quando necessário. - O timezone é o da configuração da aplicação, não necessariamente o timezone da string de entrada. - `formatMonthYearFull()` usa `Str::title()` após `isoFormat()`. - Não usar o helper para cálculos de prazo do domínio; usar Carbon/serviço de regra e formatar apenas na saída.",
      "line": 15
    },
    {
      "id": "checklist",
      "level": 2,
      "title": "Checklist",
      "text": "- [x] Implementar os seis formatos. - [x] Tratar `null` com placeholder `-`. - [x] Aplicar timezone configurado. - [x] Expor funções correspondentes em `app/helpers.php`. - [x] Testar `DateTimeImmutable` e conversão de UTC para `America/Sao_Paulo`. - [ ] Adicionar testes para mês por extenso, relativo, entrada inválida e mudança de timezone. - [ ] Confirmar locale de `Carbon` em todos os ambientes.",
      "line": 22
    },
    {
      "id": "relacionamentos",
      "level": 2,
      "title": "Relacionamentos",
      "text": "- [Funções globais](doc:helper-funcoes-globais) - [Providers](doc:providers)",
      "line": 32
    }
  ],
  "sourcePath": "content/helper-datehelper.md",
  "visuals": [],
  "apiVersion": 1
}