{
  "id": "helper-funcoes-globais",
  "title": "Helper — Funções globais",
  "description": "Funções globais carregadas pelo Composer que delegam a helpers de domínio.",
  "type": "technical-reference",
  "status": "implemented",
  "visibility": "public",
  "tags": [
    "sge/helpers",
    "sge/formatacao"
  ],
  "related": [
    "helpers",
    "helper-datehelper",
    "helper-currencyhelper",
    "helper-numbertowordshelper",
    "helper-digitshelper",
    "helper-braziliandocumenthelper",
    "helper-braziliancontacthelper",
    "helper-brazilianaddresshelper",
    "componentes-tecnicos"
  ],
  "sourceRefs": [
    "https://github.com/sge-suite/sge/blob/master/app/helpers.php"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Como são carregadas\n\nO arquivo é registrado em `composer.json` no autoload `files`, portanto as funções ficam disponíveis sem `use` após o autoload do Composer. Cada função verifica `function_exists()` antes de declarar e delega para uma classe final em `App\\Helpers`.\n\n## Catálogo\n\n| Função                  | Delegação                                  |\n| ----------------------- | ------------------------------------------ |\n| `formatDate()`          | `DateHelper::format()`                     |\n| `formatShort()`         | `DateHelper::formatShort()`                |\n| `formatDateTime()`      | `DateHelper::formatDateTime()`             |\n| `formatRelative()`      | `DateHelper::formatRelative()`             |\n| `formatMonthYear()`     | `DateHelper::formatMonthYear()`            |\n| `formatMonthYearFull()` | `DateHelper::formatMonthYearFull()`        |\n| `formatCurrency()`      | `CurrencyHelper::format()`                 |\n| `numberToWords()`       | `NumberToWordsHelper::cardinal()`          |\n| `brlToWords()`          | `NumberToWordsHelper::brl()`               |\n| `unmask()`              | `DigitsHelper::only()`                     |\n| `formatCpf()`           | `BrazilianDocumentHelper::formatCpf()`     |\n| `formatCnpj()`          | `BrazilianDocumentHelper::formatCnpj()`    |\n| `formatCpfCnpj()`       | `BrazilianDocumentHelper::formatCpfCnpj()` |\n| `formatPhone()`         | `BrazilianContactHelper::formatPhone()`    |\n| `formatCep()`           | `BrazilianAddressHelper::formatCep()`      |\n\n## Regra de uso\n\n- Use funções globais em Blade/Livewire quando a chamada ficar mais legível.\n- Use classes diretamente em PHP de domínio, testes ou quando a origem da regra precisar ser explícita.\n- Não adicionar regra nova somente na função global; implemente na classe e delegue.\n- Não usar helpers para autorização, consulta ao banco, mutação ou efeitos colaterais.\n\n## Checklist\n\n- [x] Registrar o arquivo no autoload do Composer.\n- [x] Criar guardas `function_exists()`.\n- [x] Manter delegação um-para-um para as classes de helper.\n- [x] Expor `numberToWords()` e `brlToWords()` como fachada do `NumberToWordsHelper`.\n- [ ] Criar teste de contrato para cada função global; `numberToWords()` e `brlToWords()` já são cobertos em `NumberToWordsHelperTest`.\n- [ ] Documentar colisões de nomes com pacotes/framework antes de adicionar função.\n- [x] Executar `composer dump-autoload` após criar/renomear função.\n- [x] Atualizar [Helpers](doc:helpers) ao alterar o catálogo.\n\n## Relacionamentos\n\n- [DateHelper](doc:helper-datehelper)\n- [CurrencyHelper](doc:helper-currencyhelper)\n- [NumberToWordsHelper](doc:helper-numbertowordshelper)\n- [DigitsHelper](doc:helper-digitshelper)\n- [BrazilianDocumentHelper](doc:helper-braziliandocumenthelper)\n- [BrazilianContactHelper](doc:helper-braziliancontacthelper)\n- [BrazilianAddressHelper](doc:helper-brazilianaddresshelper)\n- [Componentes técnicos](doc:componentes-tecnicos)",
  "sections": [
    {
      "id": "como-sao-carregadas",
      "level": 2,
      "title": "Como são carregadas",
      "text": "O arquivo é registrado em `composer.json` no autoload `files`, portanto as funções ficam disponíveis sem `use` após o autoload do Composer. Cada função verifica `function_exists()` antes de declarar e delega para uma classe final em `App\\Helpers`.",
      "line": 1
    },
    {
      "id": "catalogo",
      "level": 2,
      "title": "Catálogo",
      "text": "| Função                  | Delegação                                  | | ----------------------- | ------------------------------------------ | | `formatDate()`          | `DateHelper::format()`                     | | `formatShort()`         | `DateHelper::formatShort()`                | | `formatDateTime()`      | `DateHelper::formatDateTime()`             | | `formatRelative()`      | `DateHelper::formatRelative()`             | | `formatMonthYear()`     | `DateHelper::formatMonthYear()`            | | `formatMonthYearFull()` | `DateHelper::formatMonthYearFull()`        | | `formatCurrency()`      | `CurrencyHelper::format()`                 | | `numberToWords()`       | `NumberToWordsHelper::cardinal()`          | | `brlToWords()`          | `NumberToWordsHelper::brl()`               | | `unmask()`              | `DigitsHelper::only()`                     | | `formatCpf()`           | `BrazilianDocumentHelper::formatCpf()`     | | `formatCnpj()`          | `BrazilianDocumentHelper::formatCnpj()`    | | `formatCpfCnpj()`       | `BrazilianDocumentHelper::formatCpfCnpj()` | | `formatPhone()`         | `BrazilianContactHelper::formatPhone()`    | | `formatCep()`           | `BrazilianAddressHelper::formatCep()`      |",
      "line": 5
    },
    {
      "id": "regra-de-uso",
      "level": 2,
      "title": "Regra de uso",
      "text": "- Use funções globais em Blade/Livewire quando a chamada ficar mais legível. - Use classes diretamente em PHP de domínio, testes ou quando a origem da regra precisar ser explícita. - Não adicionar regra nova somente na função global; implemente na classe e delegue. - Não usar helpers para autorização, consulta ao banco, mutação ou efeitos colaterais.",
      "line": 25
    },
    {
      "id": "checklist",
      "level": 2,
      "title": "Checklist",
      "text": "- [x] Registrar o arquivo no autoload do Composer. - [x] Criar guardas `function_exists()`. - [x] Manter delegação um-para-um para as classes de helper. - [x] Expor `numberToWords()` e `brlToWords()` como fachada do `NumberToWordsHelper`. - [ ] Criar teste de contrato para cada função global; `numberToWords()` e `brlToWords()` já são cobertos em `NumberToWordsHelperTest`. - [ ] Documentar colisões de nomes com pacotes/framework antes de adicionar função. - [x] Executar `composer dump-autoload` após criar/renomear função. - [x] Atualizar [Helpers](doc:helpers) ao alterar o catálogo.",
      "line": 32
    },
    {
      "id": "relacionamentos",
      "level": 2,
      "title": "Relacionamentos",
      "text": "- [DateHelper](doc:helper-datehelper) - [CurrencyHelper](doc:helper-currencyhelper) - [NumberToWordsHelper](doc:helper-numbertowordshelper) - [DigitsHelper](doc:helper-digitshelper) - [BrazilianDocumentHelper](doc:helper-braziliandocumenthelper) - [BrazilianContactHelper](doc:helper-braziliancontacthelper) - [BrazilianAddressHelper](doc:helper-brazilianaddresshelper) - [Componentes técnicos](doc:componentes-tecnicos)",
      "line": 43
    }
  ],
  "sourcePath": "content/helper-funcoes-globais.md",
  "visuals": [],
  "apiVersion": 1
}