Adicionar uma segunda entidade de domínio

Este guia mostra como adicionar uma segunda entidade de domínio seguindo o mesmo padrão dos exemplos integrados Note e Tag.

Pré-requisito: Ter concluído Adicionar endpoint com banco de dados.

---

Visão geral

Cada entidade segue a mesma estrutura:

src/Example/YourEntity/
  YourEntity.php
  YourEntityRepositoryInterface.php
  PdoYourEntityRepository.php
  GetYourEntityByIdHandler.php
  YourEntityRouteRegistrar.php   ← registra rotas via __invoke(Router)
  YourEntityServiceProvider.php  ← configuração DI + registrar de rotas

Apenas RuntimeServiceProvider recebe o novo registrar e o handler de exceção — RuntimeApplicationFactory não precisa ser alterado.

---

Etapas principais

1 — RouteRegistrar

Parâmetros de caminho (ex.: id em /products/{id}) são lidos nos handlers via Router::PARAMETERS_ATTRIBUTE, não como atributos PSR-7 individuais:

$params = $request->getAttribute(Router::PARAMETERS_ATTRIBUTE, []);
$id     = (int) ($params['id'] ?? 0);
// $request->getAttribute('id') sempre retorna null.

final readonly class ProductRouteRegistrar
{
    public function __construct(
        private GetProductByIdHandler $getHandler,
        private ListProductsHandler $listHandler,
    ) {}

    public function __invoke(Router $router): void
    {
        $get  = $this->getHandler;
        $list = $this->listHandler;
        $router->get('/examples/products', static fn ($r) => $list->handle($r));
        $router->get('/examples/products/{id}', static fn ($r) => $get->handle($r));
    }
}

2 — ServiceProvider

Registre o registrar com a chave nene2.route_registrar.product em register().

3 — Configurar no RuntimeServiceProvider

$builder->addProvider(new ProductServiceProvider());

// set() após addProvider() substitui um único serviço (último a escrever vence).
// $builder->set(RuntimeApplicationFactory::class, static fn($c) => new RuntimeApplicationFactory(/* ... */));

return new RuntimeApplicationFactory(
    /* ... */,
    [$noteNotFoundHandler, $tagNotFoundHandler, $productNotFoundHandler],
    $requestIdHolder,
    [$noteRegistrar, $tagRegistrar, $productRegistrar],
    $bearerMiddleware,
);

Para mais detalhes, consulte a versão em inglês ou os exemplos Note/Tag em src/Example/.