MadWire vs REST

Duas perguntas diferentes têm duas respostas diferentes neste framework: "como o browser atualiza um pedaço da tela sem recarregar a página?" é o MadWire; "como um sistema externo (mobile, integração, terceiro) lê e grava dados em JSON?" é a API REST. São mecanismos independentes, com bases de código, autenticação e contratos de payload diferentes — misturar os dois é o erro mais comum ao decidir onde colocar um novo endpoint.

Tabela de decisão

MadWire — /app/_mad-wire e /public/_mad-wire

As duas rotas convergem para a mesma implementação — Mad\Component\MadComponentHandler::process($_POST) — só muda o controller que a chama: MadAppController::wire() no admin (atrás de mad.auth) ou MadSiteWireController::handle() em páginas públicas reativas (MadSitePage, sem sessão admin). Você nunca escreve código que chama esse endpoint diretamente — ele é disparado automaticamente pelo mad-livewire.js sempre que um elemento com mad:click, mad:model ou mad:submit dispara.

// app/components/admin/ProdutoListagem.php — MadComponent reativo
class ProdutoListagem extends MadDataGrid
{
    protected static string $wrapper = self::INTERNAL;
    protected string $model = Produto::class;

    public function onFiltrar(MadRequest $req): void
    {
        $this->busca = $req->string('busca');
        // auto-bind: o framework compara o estado antes/depois e gera as ops sozinho
    }

    protected function view(): string|array
    {
        return 'admin.produto-listagem';
    }
}

// Nunca chamado direto pelo dev — o JS posta automaticamente em mad:click/mad:model:
// POST /app/_mad-wire   { mad_state, mad_id, mad_action: 'onFiltrar', mad_model: {...} }

Detalhes do que acontece dentro do handler (decriptação do estado, diff de props, geração de ops parciais) ficam em MadWire por dentro.

REST API — Mad\Rest\ApiResourceController

A camada REST do framework (packages/mad-framework/src/mad/rest/) tem como base abstrata o Mad\Rest\ApiResourceController: CRUD completo sobre um model Eloquent, casando com Route::apiResource — a subclasse só declara configuração (model, campos pesquisáveis/ordenáveis, eager-load, projeção), as ações index/show/store/update/destroy vêm prontas da base.

// app/control/api/ProdutoApiController.php — REST puro, sem MadComponent
use Mad\Rest\ApiResourceController;

class ProdutoApiController extends ApiResourceController
{
    protected string $model      = \App\Models\Produto::class;
    protected array  $searchable = ['nome', 'categoria_id'];
    protected array  $sortable   = ['nome', 'preco'];
    protected ?string $defaultOrder = 'nome asc';
}

// routes/web.php
Route::middleware('mad.auth')->prefix('api')->group(function () {
    Route::apiResource('produtos', ProdutoApiController::class);
});

// GET /api/produtos?filters[categoria_id][eq]=5&sort=preco&per_page=20
// -> { "data": [...], "meta": { "total": 42, "per_page": 20, ... } }

A base já cobre mestre-detalhe (múltiplas relações hasMany sincronizadas por diff de PK — cria/atualiza/apaga), um DSL de filtros declarativo (eq, like, between, in, is_null...), validação via Model::rules(), hooks (authorize, beforeSave/afterSave, beforeSaveDetail/afterSaveDetail, beforeDelete) e transação atômica na conexão do model. A referência completa — incluindo o formato exato de request/response, o algoritmo de sync de detalhes e os gotchas de concorrência — está em packages/mad-framework/src/mad/rest/README.md.

Os 3 aliases de middleware registrados pelo pacote

Mad\MadServiceProvider::bootRoutes() registra exatamente três aliases que você usa em routes/web.php:

Não confundir com o REST Driver (HMAC)

Quando usar cada um

Próximos passos