README

Declarative APIs. Zero boilerplate.

Define your entire HTTP pipeline — routing, validation, service binding, authorization, and response shaping — with PHP 8 attributes. Your controller methods stay empty. The framework does the wiring.

#[Route(path: 'users/{id}', methods: ['GET'], auth: 'sanctum', authorized: ['can_manage_users'])]
#[Request(GetUserByIdRequest::class, GetUserByIdDTO::class)]
#[Service(GetUserByIdService::class, 'User found.', 200)]
#[Response(UserResource::class)]
#[Doc(summary: 'Get a user by ID')]
public function show() {}  // That's it. The entire endpoint.

First-class Laravel (Symfony support coming soon) adapters. OpenAPI generation from the same attributes. Under 2ms pipeline overhead.

Why Zolta HTTP?

The problem

PHP frameworks give you routing and controllers, but the plumbing between "HTTP request" and "business logic" is still manual. Every endpoint repeats the same pattern: validate input → map to DTO → call service → transform result → shape response. This boilerplate multiplies across hundreds of endpoints, and every copy is a place for inconsistencies to hide.

What Zolta HTTP does differently

Approach	How it works	Trade-off
Laravel Resource Controllers	Convention-based CRUD + manual service calls	Still wiring validation, DTOs, responses by hand
Symfony API Platform	Schema-driven REST/GraphQL generation	Heavy, opinionated, hard to customize beyond CRUD
Spatie Query Builder	Query parameter parsing for Eloquent	Read-only filtering, no full pipeline
Zolta HTTP	Full pipeline declared in attributes — routing to response	True zero-boilerplate endpoints, dual framework support

The key insight: your controller method shouldn't contain the pipeline — it should declare it. Five attributes replace what typically takes 30-50 lines of wiring code per endpoint.

Who is this for?

Teams building API-first applications who are tired of repetitive controller boilerplate
Projects targeting both Laravel and Symfony with shared HTTP logic
Developers who want convention with escape hatches — use attributes for 90% of endpoints, drop to manual for the rest

Install

composer require zolta/http

Laravel auto-discovers the service provider. For Symfony, register the bundle in config/bundles.php.

The pipeline — from request to response

Every attribute-routed request flows through a deterministic pipeline:

HTTP Request
  ↓ RouteMetadataResolver   — Combine class + method attributes (cached)
  ↓ RouteConfigValidator     — Validate controller setup
  ↓ Authorization            — Check gates from #[Route] authorized
  ↓ FormRequest validation   — Apply rules from #[Request]
  ↓ DTO mapping              — Map validated data to typed object
  ↓ ServiceInvoker           — Call the bound service class
  ↓ ResourceTransformer      — Apply #[Response] resource transformation
  ↓ ResponseFactory          — Wrap in standardized envelope
HTTP Response

Each step is independently replaceable. The entire pipeline adds < 2ms overhead on warm requests.

Quick start

1. Define a controller

Controllers are declaration sites, not logic containers. Each method declares what should happen via attributes — the framework handles how:

use Zolta\Http\Controller\Controller;
use Zolta\Http\Router\Attributes\Route;
use Zolta\Http\Request\Attributes\Request;
use Zolta\Http\Service\Attributes\Service;
use Zolta\Http\Response\Attributes\Response;
use Zolta\Http\Service\Attributes\Doc;

final class UserController extends Controller
{
    #[Route(path: 'users/{id}', methods: ['GET'], auth: 'sanctum', authorized: ['can_manage_users'])]
    #[Request(GetUserByIdRequest::class, GetUserByIdDTO::class)]
    #[Service(GetUserByIdService::class, 'User found.', 200)]
    #[Response(UserResource::class)]
    #[Doc(summary: 'Get a user by ID')]
    public function show() {}
}

2. Define a form request

use Zolta\Http\Request\BaseRequest;

final class GetUserByIdRequest extends BaseRequest
{
    public function rules(): array
    {
        return ['id' => 'required|string|min:1'];
    }

    public function routeParams(): array
    {
        return ['id' => ['type' => 'string', 'required' => true]];
    }
}

3. Define an input DTO

use Zolta\Support\Application\DTO\Input\InputDTO;
use Zolta\Support\Application\Attributes\FromRequest;

class GetUserByIdDTO extends InputDTO
{
    final public function __construct(
        #[FromRequest('id')]
        public readonly string $id,
        public readonly array $options = []
    ) {}
}

4. Define a resource

use Zolta\Http\Response\Resources\Resource;

final class UserResource extends Resource
{
    public function toArray(): array
    {
        return [
            'user' => $this->all()['user'],
        ];
    }
}

Attribute reference

Attribute	Target	Purpose
`#[Route]`	Class / Method	Defines path, HTTP methods, middleware, auth, authorization
`#[Request]`	Class / Method	Binds a form request class and optional input DTO
`#[Service]`	Class / Method	Binds a service class, success message, and HTTP status
`#[Response]`	Class / Method	Binds a resource class for response transformation
`#[Doc]`	Class / Method	OpenAPI documentation metadata (summary, description, tags)
`#[View]`	Class / Method	Server-side view rendering (view name, engine)

Authorization

Configure the AuthorizationMatrix to map abilities to permissions, with multi-path extraction from your user model:

AuthorizationMatrix::configure([
    'abilities' => [
        'can_manage_users' => ['users.read', 'users.write'],
    ],
    'user' => [
        'class' => User::class,
        'attributes' => ['permissions', 'role.permissions', 'roles.*.permissions'],
    ],
]);

Then reference abilities in your route attribute — authorization is checked before the service is invoked:

#[Route(path: '/users/{id}', auth: 'sanctum', authorized: ['can_manage_users'])]

Response format

All responses follow a consistent envelope — success, error, and debug states share the same shape:

{
    "success": true,
    "message": "User found.",
    "data": { "user": { "id": "123", "name": "John" } },
    "errors": [],
    "debug": []
}

Exceptions are automatically normalized: domain exceptions (404, 409, 422) pass through with context; unexpected errors become safe 500 responses with debug trace in development mode.

What else is included

OpenAPI generation from attributes

The same #[Route], #[Request], #[Response], and #[Doc] attributes that drive runtime behavior also generate OpenAPI 3.0 specifications. No separate schema files to maintain — your docs always match your code.

Multi-tier reflection caching

Route metadata resolution uses a 3-tier cache: runtime memory → persistent store (Laravel Cache / APCu) → reflection fallback. Cold-start resolves once, then subsequent requests hit the cache at < 0.5ms.

Route caching with manifest tracking

AttributeRouteCache compiles routes into bootstrap/cache/attribute_routes.php with file-level tracking — only changed controllers trigger rebuilds.

php artisan zolta:routes:cache    # Build route cache
php artisan zolta:routes:clear    # Clear route cache
php artisan zolta:routes:watch    # Watch for file changes in development

Exception handling

The HandlesApiExceptions trait normalizes all exceptions into the standard response envelope. Domain exceptions (ValidationException, NotFoundException, ConflictException) carry structured error data; framework exceptions are safely wrapped.

File upload support

UploadedFileDTO provides a framework-neutral representation with clientOriginalName, clientMimeType, size, tmpPath, and error — works identically on Laravel and Symfony.

Performance

Benchmarked on a real application (Laravel 12, PHP 8.3, SQLite):

Pipeline step	Time (warm)
RouteMetadataResolver	1.3–1.9ms
RouteConfigValidator	< 0.01ms
ServiceInvoker overhead	< 0.5ms
ResourceTransformer	0.5–0.7ms
ResponseFactory	0.5–0.6ms
Total HTTP pipeline overhead	< 2ms

The rest of your request time is your application logic — Eloquent queries, external calls, business rules. The transport layer stays invisible.

Dual framework support

Every module has independent Laravel adapter (Symfony support is coming soon). The same controller code runs on either framework without modification.:

Feature	Laravel	Symfony
Attribute routing	✅	coming soon
Form request validation	✅	coming soon
DTO mapping	✅	coming soon
Authorization	✅	coming soon
Exception handling	✅	coming soon
Response shaping	✅	coming soon
View rendering	✅	coming soon
OpenAPI generation	✅	coming soon
Route caching	✅	coming soon
Reflection caching	✅	coming soon

Write your controllers once, deploy on either framework.

QA

composer run qa          # Full suite: lint + analyse + phpmd + rector + test
composer run test        # PHPUnit only

146 tests, 323 assertions covering routing attributes, authorization matrix, request mapping, response contracts, exception handling, caching, and security.

Part of the Zolta Ecosystem

Zolta HTTP is the transport layer — it wires HTTP to your application through clean attributes:

┌─────────────────────────────────────────────┐
│  zolta/http (Transport) ← you are here      │
│  Attribute-driven routing & response        │
├─────────────────────────────────────────────┤
│  zolta/cqrs (Application)                   │
│  Commands, queries, events, transactions    │
├─────────────────────────────────────────────┤
│  zolta/forge (Domain)                       │
│  Value Objects, rules, specs, entities      │
└─────────────────────────────────────────────┘

When used together: a request arrives → HTTP resolves the pipeline via attributes → Forge hydrates the command with validated VOs → CQRS dispatches through the bus, captures events, wraps transactions → HTTP transforms and returns the response. All of this happens with < 5ms of package overhead and zero manual wiring.

Package	Layer	Link
zolta/forge	Domain	`packages/forge`
zolta/cqrs	Application	`packages/cqrs`
zolta/http	Transport	You are here

Documentation

Full documentation is available in the docs/ directory, organized for serving via Nuxt Content.

zolta / http

Maintainers

Package info

Statistics

Security