LiquidRazor/DtoApiBundle

DTO-first API toolkit for Symfony 7.x
Attributes for request/response contracts, automatic validation, safe (de)serialization, streaming (NDJSON/SSE), OpenAPI generation, and Symfony Profiler integration.

---

---

✨ Features

• Attributes for requests, responses, operations, and properties
• Validation bridge: property metadata → Symfony constraints (no YAML/XML)
• Safe request hydration via events (no fatals, no leaks)
• Response mapping with global defaults (422/500)
• Error handling: exceptions → mapped error DTOs
• Streaming helpers: NDJSON (application/x-ndjson) and SSE (text/event-stream)
• OpenAPI 3.1/3.0.3 generator with Swagger UI + Redoc
• Profiler panel: metadata, DTOs, violations, and the actual response used

---

🧰 Requirements

• PHP 8.3+
• Symfony 7.0+
• packages: (already present in composer.json)
  • ext-json
  • symfony/dependency-injection
  • symfony/config
  • symfony/http-kernel
  • symfony/serializer
  • symfony/property-access
  • symfony/options-resolver
  • symfony/validator
  • monolog/monolog

---

📦 Install

composer require liquidrazor/dto-api-bundle

Enable the bundle (if Flex doesn’t auto-register):

config/bundles.php

return [
    ...
    LiquidRazor\DtoApiBundle\LiquidRazorDtoApiBundle::class => ['all' => true],
];

⚙️ Configuration

Responses

# config/packages/liquidrazor_dto_api.yaml
liquidrazor_dto_api:
  normalizer_priority: 10
  strict_types: true
  openapi_version: '3.1.0'   # or '3.0.3' for Redoc OSS compatibility
  default_responses:
    422:
        class: LiquidRazor\DtoApiBundle\Response\ValidationErrorResponse
        description: 'Validation error'
    500:
        class: LiquidRazor\DtoApiBundle\Response\ErrorResponse
        description: 'Server error'

Edit the file and set up any custom response classes (and|or descriptions)

This is the default configuration and should be there if flex auto-registered the bundle. Otherwise it's probably missing and should be added.

Routes

add the following to your routes.yaml (if not already added by symfony flex)

# config/routes/liquidrazor_dto_api.yaml
liquidrazor_dto_api:
  resource: '@LiquidRazorDtoApiBundle/Resources/config/routes.php'

You now get:

• /_schema/openapi.json — OpenAPI spec
• /_docs/swagger — Swagger UI
• /_docs/redoc — Redoc UI

🚀 Usage Guides

1. Request DTO

use LiquidRazor\DtoApiBundle\Lib\Attributes\{DtoApiRequest, DtoApiProperty};

#[DtoApiRequest(name: 'UserInput')]
final readonly class UserInputDto
{
    public function __construct(
        #[DtoApiProperty(type: 'string', required: true, minLength: 3)]
        public ?string $name = null,

        #[DtoApiProperty(type: 'integer', required: true, minimum: 18, maximum: 100)]
        public ?int $age = null,
    ) {}
}

Validation is automatic — missing/invalid fields trigger a 422 ValidationErrorResponse (unless you override the default response).

2. Response DTO

use LiquidRazor\DtoApiBundle\Lib\Attributes\{DtoApiResponse, DtoApiProperty};

#[DtoApiResponse(status: 200, description: 'User created')]
final readonly class UserResponse
{
    public function __construct(
        #[DtoApiProperty(type: 'string')] public string $id,
        #[DtoApiProperty(type: 'string')] public string $name,
    ) {}
}

3. Controller

use LiquidRazor\DtoApiBundle\Lib\Attributes\{DtoApi, DtoApiOperation};
use Symfony\Component\Routing\Attribute\Route;

#[DtoApi]
final class UserController
{
    #[DtoApiOperation(
        summary: 'Create user',
        description: 'Accepts a UserInputDto and returns a UserResponse',
        request: UserInputDto::class,
        response: [UserResponse::class] // 422/500 added by defaults
    )]
    #[Route('/users', methods: ['POST'])]
    public function create(UserInputDto $request): UserResponse
    {
        return new UserResponse(id: uniqid(), name: $request->name);
    }
}

4. Error Handling

All exceptions are logged

Mapped to a declared #[DtoApiResponse(status: …)] if present

Fallback: ErrorResponse (500 JSON)

5. Streaming

5.1 NDJSON

#[DtoApiOperation(summary: 'NDJSON counter')]
#[DtoApiResponse(status: 200, stream: true, contentType: 'application/x-ndjson')]
#[Route('/stream/ndjson', methods: ['GET'])]
public function streamNdjson(): iterable
{
    for ($i=1; $i<=5; $i++) {
        yield ['i' => $i, 'ts' => (new \DateTimeImmutable())->format(DATE_ATOM)];
        usleep(200_000);
    }
}

5.2 SSE

use LiquidRazor\DtoApiBundle\Lib\Streaming\SseEvent;

#[DtoApiOperation(summary: 'SSE clock')]
#[DtoApiResponse(status: 200, stream: true, contentType: 'text/event-stream')]
#[Route('/stream/sse', methods: ['GET'])]
public function sseClock(): iterable
{
    for ($i=0; $i<5; $i++) {
        yield new SseEvent(['now' => date(DATE_ATOM)], 'tick', (string)$i, 3000);
        sleep(1);
    }
}

6. Profiler

Symfony Profiler panel shows:

Operation metadata (summary, request/response DTOs)

Request violations (422 errors)

Which response mapping was actually used.

🧩 Extensibility

• Custom constraints: tag dtoapi.constraint_contributor to translate custom hints into Symfony constraints
• Global defaults: override liquidrazor_dto_api.default_responses
• OpenAPI hooks: extend components, security, servers, parameters

📍 Known limitations

• Very strict CSP may require self-hosting Swagger/Redoc assets instead of using CDNs

📝 License

MIT

🙌 Credits

Built by LiquidRazor with help from Symfony’s excellent components.