Helpers · PHP MVC Framework

Helpers de aplicação

Em app/Support/Helpers/functions.php: URL/assets (url, asset, storageUrl, uploadUrl, route), redirect (redirect, safeRedirectTarget), flash/erros/old input (flash, hasFlash, old, errors, hasError, error), CSRF (csrf_field, csrf_token), escape (e), override de método (method_field), autenticação (auth, user, userId, userRole, isRole), ambiente, strings, datas, bytes e navegação (env, str_limit, slug, dateBR, dateTimeBR, diffForHumans, formatBytes, isActive, dump, dd).

Helpers de views

ViewHelper.php define emptyDataMessage, inputClass, erroInput, selected, checked, disabledIf, readonlyIf, oldOr, oldSelected, oldChecked, classNames, attr, paginationLinks, money, pluralize, initials e imageOr.

Segurança e escopo

SecurityHelper reúne gerar token, hash/verify de password, sanitização, e-mail válido, slug, mask de email e UUID v4. Mailer envia ou simula envio conforme driver. Helpers simplificam apresentação; não substituem validação/autorização. Escape strings dinâmicas com e().

<input value="<?= old('title', $post->title ?? '') ?>">
<option value="draft" <?= selected('draft', $status) ?>>Rascunho</option>

Helpers mais usados no fluxo Web

Problema	Helpers	Retorno/atenção
Montar URL	url($path), asset($path), route($name,$params)	URL base, asset sob assets/ e rota nomeada.
Exibir valor com segurança	e($value)	String escapada para HTML; aplicar na saída.
Repopular formulário	old($key,$default), oldOr(...)	Valor anterior; escape no atributo/HTML.
Mostrar validação	hasError($field), error($field), errors()	Inspeciona erros da sessão atual.
CSRF/método HTML	csrf_field(), csrf_token(), method_field($method)	Token e override para métodos além de GET/POST.
Estado de autenticação	auth(), user(), userId(), userRole(), isRole($role)	Conveniente em View; middleware continua sendo o gate da rota.

Exemplo de template

Use helpers de apresentação para manter o template curto, mas não misture autorização com visibilidade de botão: esconder um link não protege a action. Continue validando e autorizando no servidor.

<form method="POST" action="<?= e(url('auth/login')) ?>">
    <?= csrf_field() ?>
    <input name="email" value="<?= old('email') ?>">
    <?php if (hasError('email')): ?>
        <span><?= e(error('email')) ?></span>
    <?php endif; ?>
</form>

ViewHelper também contém helpers de classe CSS, formatação monetária, paginação, iniciais e imagem fallback. São funções globais de app/Support/Helpers/ViewHelper.php; consulte a referência completa para nomes e assinaturas.

Contrato dos helpers de formulário e apresentação

Os helpers são funções globais carregadas pelo autoload do projeto. Abaixo estão os contratos que afetam formulários, navegação, paginação e exibição; a referência de API lista todos os parâmetros/tipos extraídos.

Função	Contrato/retorno	Uso e observações
`old(string $key, string $default = ''): string`	String escapada para HTML	Repõe o valor e já aplica escaping; não chame e() novamente.
`oldOr($key, $fallback)`	Combina old input e fallback	old() escapa o valor anterior; o fallback pode voltar cru. Evite usar em saída não confiável sem tratar cada ramo.
`e(mixed $value): string`	Texto escapado	Escapa HTML; arrays viram JSON e objetos sem __toString viram nome da classe.
`error($field): string`, `errors(): array`	Mensagens sem escape	Aplique e() ao imprimir mensagem em HTML, como faz o componente alerts.php.
`method_field(string $method): string`	Input hidden _method	Recebe string, por exemplo `method_field('PUT')`; não passe identificador sem aspas.
`csrf_field(): string`, `csrf_token(): string`	Campo HTML ou token	Usados em forms e metadado; CsrfMiddleware precisa estar associado à rota.
`route($name, $params = []): string`	URL de rota nomeada	Se a resolução falhar, registra erro e cai para a URL da aplicação; não equivale a validação de rota.
`redirect($path): never`, `safeRedirectTarget(...): string`	Redirecionamento terminal/alvo seguro	URLs externas não confiáveis são rejeitadas pelo helper de destino seguro.
`cspNonce(): string`	Retorna CSP_NONCE ou string vazia	Não gera valor aleatório; depende de constante definida pela aplicação.

ViewHelper: classes, estados e apresentação

ViewHelper.php define 17 funções globais. selected()/checked() devolvem fragmentos HTML para controles; disabledIf()/readonlyIf() produzem atributos conforme condição. inputClass()/erroInput() ajudam a mostrar validação, mas os valores/classes passados não são todos escapados automaticamente.

Função	Parâmetros/retorno	Observações
`emptyDataMessage(string $message = 'Não há dados para serem exibidos.'): string`	Gera span com mensagem escapada	Recebe a mensagem final; não aceita contagem nem pluraliza.
`oldSelected(string $field, mixed $value, mixed $fallback = null): string`, `oldChecked(...)`	Fragmento de atributo HTML	Compara entrada antiga com valor atual; revisar escaping no contexto do atributo.
`classNames(array $classes): string`	String com classes ativas	Não escapa automaticamente tokens de classe.
`attr(string $name, mixed $value): string`	Fragmento de atributo	Escapa o valor, não é um sanitizador de nome de atributo.
`paginationLinks(array $pagination, string $baseUrl, string $pageParam = 'page', int $window = 2): string`	HTML de navegação	Contrato diferente de components/pagination.php; recebe base URL e nomes de paginação explicitamente.
`money(float\|int\|string $value, string $prefix = 'R$ '): string`, `pluralize(...)`	Strings formatadas	Helpers de apresentação; não validam entrada de negócio.
`initials(string $name, int $max=2): string`	Iniciais	Ignora conectores comuns e limita quantidade por max.
`imageOr(?string $path, string $fallback): string`	URL de asset ou fallback	Só testa arquivo no disco se PUBLIC_PATH estiver definido; sem a constante retorna o fallback.

Dois contratos de paginação

// Componente real: recebe o resultado de Model::paginate dentro de data.


// Helper global: recebe resultado e URL base como argumentos distintos.
echo paginationLinks($result, url('users'), 'page', 2);

Não trate paginationLinks() e components/pagination.php como a mesma API: um produz links a partir de baseUrl/pageParam/window; o componente lê $_GET e espera o array em $data.

Override de método e escaping em template

method_field(string $method): string gera o campo oculto para enviar PUT/PATCH/DELETE em um formulário HTML POST. O Router só honra esses três valores em POST; a função não acrescenta novos verbos suportados nem converte uma requisição GET em PUT.

<form method="POST" action="/users/42">
    <?= csrf_field() ?>
    <?= method_field('PUT') ?>
    <button type="submit">Salvar</button>
</form>

old('email') já retorna valor escapado para HTML; use value="<?= old('email') ?>", sem e() adicional. Se oldOr() devolver o fallback cru, escape esse ramo de acordo com o contexto de saída.