Helpers — Infraestrutura & Ferramentas

Funções globais disponíveis em qualquer controller, view ou middleware das rotas públicas do MAD (Mad\Web\* — o roteador leve usado por portais de cliente, cadastro/login público e esta própria documentação). Carregadas via composer autoload "files", sempre disponíveis sem use.

Esta é uma camada deliberadamente fina e independente da sessão HTTP do Laravel — não confunda com as props/actions de um MadComponent (telas administrativas reativas), que seguem outro ciclo de vida. Para essas, veja Visão geral do MadWire.

#Render — view()

view(string $template, array $data = [], int $statusCode = 200): ViewResponse

Renderiza Blade e retorna um ViewResponse chainable:

return view('public.home');
return view('public.home', ['titulo' => 'Olá']);
return view('public.errors.404', ['msg' => 'Não existe'], 404);

#Redirect — redirect() / back()

redirect(?string $url = null, int $statusCode = 302): RedirectResponse
back(int $statusCode = 302): RedirectResponse

return redirect('/public/destino');
return redirect('/public/destino', 301);
return redirect('/public/erro')->with('error', 'Algo deu errado');

// Volta pra HTTP_REFERER (fallback pra /public/)
return back();
return back()->with('error', 'Voltou')->withInput();

#RedirectResponse — métodos chainable

Método	Descrição
`->with($key, $value)`	Adiciona 1 flash message (disponível só na próxima request).
`->withMany(array $values)`	Múltiplos flash messages de uma vez.
`->withInput(?array $input = null)`	Salva o input atual (ou um array customizado) como old input.
`->withErrors($errors)`	Aceita um `ErrorBag`, array ou string.

#Session — session()

session(): SessionHelper
session(string $key, mixed $default = null): mixed
session(array $values): void

// Sem argumento — helper chainable
session()->put('theme', 'dark');
session()->has('cart');
session()->forget('temp');
session()->flash('success', 'Salvo!');
session()->getFlash('success');
session()->hasFlash('error');
session()->all();
session()->regenerate();

// Com 1 argumento string — lê o valor
$theme = session('theme', 'light');

// Com array — escreve várias chaves de uma vez
session(['user_id' => 42, 'role' => 'admin']);

#Mad\Web\Session — API completa

session() é açúcar sintático sobre Mad\Web\Session — um wrapper fino sobre $_SESSION (independente da sessão do Eloquent/Auth do Laravel), com flash messages, old input, errors e CSRF token embutidos:

Método estático	Descrição
`Session::start()`	Inicia a sessão PHP (cookie HttpOnly + SameSite=Lax) se ainda não ativa.
`Session::put($k, $v)`	Grava no `$_SESSION`.
`Session::get($k, $default)`	Lê um valor.
`Session::has($k)`	Existe e não está vazio?
`Session::forget($k)`	Remove a chave.
`Session::all()`	Todos os dados da sessão.
`Session::flash($k, $v)`	Flash — disponível só na próxima request.
`Session::getFlash($k, $default)`	Lê um flash gravado na request anterior.
`Session::hasFlash($k)`	Tem flash com essa chave?
`Session::token()`	Token CSRF atual (gera se ainda não existir).
`Session::regenerateToken()`	Gera um novo token CSRF.
`Session::regenerate(bool $deleteOld = true)`	`session_regenerate_id()` — chame após login.
`Session::invalidate()`	Limpa tudo + `session_destroy()`.

#Old input — old()

old(string $key, mixed $default = null): mixed

Recupera um valor do POST anterior, gravado via redirect()->withInput() — útil para repopular um form após validação falhar:

<input name="email" value="{{ old('email') }}">
<input name="email" value="{{ old('email', $user->email ?? '') }}">

#CSRF — csrf_token() / csrf_field()

csrf_token(): string
csrf_field(): string  // HTML de um <input hidden>

<meta name="csrf-token" content="{{ csrf_token() }}">

<form method="POST">
    {!! csrf_field() !!}
    <!-- equivale a @csrf -->
</form>

#Method spoofing — method_field()

method_field(string $method): string

<form method="POST" action="/public/produtos/42">
    @csrf
    {!! method_field('PUT') !!}
    <!-- ou @method('PUT') -->
</form>

#Auth — auth()

auth(): AuthHelper

Representa o usuário público autenticado (portal de cliente) — guarda estado em session('user_public_id'/'user_public_name'/'user_public_data'), independente do guard de autenticação administrativa.

Método	Retorno	Descrição
`auth()->check()`	`bool`	Tem usuário público logado?
`auth()->guest()`	`bool`	Inverso de `check()`.
`auth()->id()`	`mixed\|null`	ID do usuário logado.
`auth()->name()`	`?string`	Nome do usuário logado.
`auth()->user()`	`?array`	Dados extras salvos no login.
`auth()->login($id, $name, $extra = [])`	`void`	Loga + regenera o ID de sessão (anti session-fixation).
`auth()->logout()`	`void`	Remove as chaves de autenticação (mantém o resto da sessão).

@auth
    Olá, {{ auth()->name() }}
@endauth

@guest
    <a href="/public/login">Entrar</a>
@endguest

#URL — url() / site_url() / asset()

url(string $path = '/'): string       // absoluta, com scheme+host
site_url(string $path = '/'): string  // relativa (path only)
asset(string $path): string           // alias de url()

Ambas respeitam deploy em subdiretório, lendo o basePath a partir de SCRIPT_NAME — não tem path hardcoded em nenhum dos dois helpers.

url('/public/login');       // → 'https://dominio.com/public/login'
                              // (ou 'https://dominio.com/subpasta/public/login' em deploy de subdiretório)

site_url('/public/login');  // → '/public/login' (só o path — ideal para href/action)

asset('/img/logo.png');     // → 'https://dominio.com/img/logo.png'

route(string $name, array $params = []) existe por compatibilidade de assinatura, mas ainda não resolve rotas nomeadas — devolve o próprio nome recebido. Use url()/site_url() com o path direto.

#config() e abort()

Não são helpers do MAD — são os helpers nativos do Laravel, disponíveis porque toda essa camada roda dentro de uma aplicação Laravel normal (carregada pelo autoload do framework). Funcionam exatamente como em qualquer app Laravel:

config(string $key, mixed $default = null): mixed
abort(int $statusCode, string $message = ''): never

public static function show(int $id)
{
    $produto = Produto::find($id);
    if (!$produto) abort(404);

    return view('public.produto-show', ['produto' => $produto]);
}

$tema = config('mad.general.theme', 'theme-builder');

#ErrorBag

use Mad\Web\ErrorBag;

$errors = new ErrorBag([
    'email' => ['Email inválido'],
    'preco' => ['Deve ser maior que 0'],
]);

$errors->has('email');   // bool
$errors->any();          // bool — algum erro, em qualquer campo
$errors->first('email'); // primeira mensagem do campo
$errors->all();          // array completo field => [mensagens]
$errors->count();        // total de mensagens

return redirect('/public/cadastro')->withErrors($errors)->withInput();

@if($errors->has('email'))
    <span>{{ $errors->first('email') }}</span>
@endif

@error('email')
    <span>{{ $message }}</span>
@enderror

#Diretivas Blade específicas

Diretiva	Equivale a
`@csrf`	`<input type="hidden" name="_token" value="...">`
`@method('PUT')`	Method spoofing — `method_field('PUT')`.
`@error('campo') ... @enderror`	Bloco condicional + `$message` injetada, lendo de `$errors` (um `ErrorBag`).
`@auth ... @endauth`	Bloco renderizado só com usuário público logado.
`@guest ... @endguest`	Bloco renderizado só sem usuário público logado.
`@site`	Ativa os assets/CSS desta página pública (`MadSiteAssets::enableSite()`).
`@sitehead('<meta ...>')`	Injeta HTML extra no `<head>` (`MadSiteAssets::pushHead()`).
`@sitebody('<script>...</script>')`	Injeta HTML extra no fim do `<body>` (`MadSiteAssets::pushBody()`).

Diretivas reativas como @madWire/@madBind pertencem ao outro mundo — o dos MadComponent administrativos — e estão documentadas em Visão geral do MadWire.