DEV Community: Dev

ApiKit — Clean REST API in Symfony Without Boilerplate

Dev — Sat, 28 Feb 2026 17:20:18 +0000

Writing REST APIs in Symfony is quite comfortable, but there's one recurring annoyance: controllers quickly become cluttered with repetitive code. Parsing the request, validating input, wrapping responses in the same JSON envelope, try/catch blocks converting exceptions into HTTP responses. None of this is hard, but over time it ends up duplicated across dozens of endpoints and distracts from the actual work.

Below is a way to bring order to all of this with a small bundle I use in my own projects.

What a Typical Controller Looks Like

public function create(Request $request): JsonResponse
{
    $data = json_decode($request->getContent(), true);

    $dto = new CreateUserDto(
        $data['email'],
        $data['name']
    );

    $errors = $this->validator->validate($dto);

    if (count($errors) > 0) {
        // every developer has their own error format
        return new JsonResponse(['errors' => (string) $errors], 422);
    }

    try {
        $user = $this->userService->create($dto);
        return new JsonResponse(['data' => $user->toArray()], 201);
    } catch (DuplicateEmailException $e) {
        return new JsonResponse(['error' => $e->getMessage()], 409);
    } catch (\Throwable $e) {
        // and this is everywhere
        return new JsonResponse(['error' => 'Internal server error'], 500);
    }
}

Sure, you might say — introduce DTOs and things will be fine. But DTOs only solve the problem of structuring and validating input. Wrapping responses in a unified format, catching exceptions from the service layer and turning them into proper JSON — that still has to be done manually, in every controller, over and over again. And each developer tends to introduce a slightly different format. Scale that across dozens of endpoints. Add three developers with different habits. The result is an inconsistent API that's hard to maintain and impossible to document automatically.

ApiKit is a lightweight Symfony bundle that solves exactly this problem: it standardizes responses, intercepts exceptions, and lets the controller do only what it's meant to do.

What It Gives Your Project

Dependencies. The bundle relies on symfony/validator and symfony/serializer — both are part of a standard Symfony project and are most likely already installed. Doctrine is optional and only needed for the EntityExists constraint.

DTOs are not required. The bundle does not require you to use DTOs. A controller can accept Request directly and still use respondSuccess/respondCreated. DTOs are a recommended pattern because they pair well with #[MapRequestPayload] and make validation declarative — but it's the developer's choice, not the bundle's requirement.

Unified response format. All successful responses share one structure, all errors share another. A frontend, a mobile app, another microservice — everyone knows what to expect:

// Successful response
{
  "success": true,
  "data": { "id": 1, "email": "user@example.com", "name": "Mr. Author" },
  "meta": { "timestamp": "2025-06-01T12:00:00+00:00" }
}

// Validation error
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "violations": [
        { "field": "email", "message": "This value is not a valid email address." }
      ]
    }
  }
}

Slim controllers. A controller handles only routing and data passing — no manual validation, no try/catch, no json_decode. Validation happens automatically via #[MapRequestPayload] and Symfony Validator; all unhandled exceptions are caught by ExceptionListener.

Kernel-level exception handling. ExceptionListener handles HttpExceptionInterface, ValidationFailedException, and any uncaught \Throwable. In the dev environment, a stack trace is appended to errors; in prod — only the message. 5xx errors are logged via a PSR-3 logger (enabled by default, controlled via log_errors in config), 4xx are not — because those are client errors.

ApiException for domain errors. Instead of building a JsonResponse directly inside services, you throw a typed exception with the desired status and details:

throw new ApiException(409, 'Email already taken', [
    'field'  => 'email',
    'reason' => 'already_taken',
]);

// Or an account lock with context
throw new ApiException(423, 'Account locked', [
    'locked_until'  => $lockedUntil->format(\DateTimeInterface::ATOM),
    'attempts_left' => 0,
]);

EntityExists constraint. An optional Doctrine validator that checks for the existence of a database record directly inside a DTO — it is wired automatically if Doctrine is installed:

#[EntityExists(Category::class, field: 'slug')]
public readonly string $categorySlug;

Custom response format. The default structure with success, data, and error works for most projects, but if your team uses a different format — the bundle supports that too. Just implement ResponseFactoryInterface and register your implementation in the container:

final readonly class MyResponseFactory implements ResponseFactoryInterface
{
    public function success(mixed $data = null, int $statusCode = 200, array $meta = []): JsonResponse
    {
        return new JsonResponse(['result' => $data, 'ok' => true], $statusCode);
    }
    // ...
}

# config/services.yaml
ApiKit\Response\ResponseFactoryInterface:
    alias: App\Api\MyResponseFactory

The entire bundle — controllers and ExceptionListener — will start using the new format automatically.

Slim Controllers in Practice

Here's a CRUD example for users. Notice: each action is 1–3 lines of logic. The #[OA\*] attributes are optional and only needed if you use nelmio/api-doc-bundle for documentation generation. Without it the controller works exactly the same — the update and delete actions below show what it looks like without OpenAPI annotations.

#[Route('/api/users', name: 'api_users_')]
#[OA\Tag(name: 'Users')]
final class UserController extends AbstractApiController
{
    public function __construct(
        private readonly UserService $userService,
    ) {}

    #[Route('', name: 'list', methods: ['GET'])]
    #[OA\Get(path: '/api/users', summary: 'List all users', responses: [
        new OA\Response(response: 200, description: 'List of users',
            content: new OA\JsonContent(type: 'array',
                items: new OA\Items(ref: new Model(type: UserResponseDto::class))))
    ])]
    public function list(): JsonResponse
    {
        return $this->respondSuccess(
            array_map(UserResponseDto::fromEntity(...), $this->userService->findAll())
        );
    }

    #[Route('', name: 'create', methods: ['POST'])]
    #[OA\Post(path: '/api/users', summary: 'Create a new user',
        requestBody: new OA\RequestBody(required: true,
            content: new OA\JsonContent(ref: new Model(type: CreateUserDto::class))),
        responses: [
            new OA\Response(response: 201, description: 'User created',
                content: new OA\JsonContent(ref: new Model(type: UserResponseDto::class))),
            new OA\Response(response: 422, description: 'Validation error'),
            new OA\Response(response: 409, description: 'Email already taken'),
        ]
    )]
    public function create(#[MapRequestPayload] CreateUserDto $dto): JsonResponse
    {
        return $this->respondCreated(
            UserResponseDto::fromEntity($this->userService->create($dto))
        );
    }

    #[Route('/{id}', name: 'update', requirements: ['id' => '\d+'], methods: ['PUT'])]
    public function update(int $id, #[MapRequestPayload] UpdateUserDto $dto): JsonResponse
    {
        return $this->respondSuccess(
            UserResponseDto::fromEntity($this->userService->update($id, $dto))
        );
    }

    #[Route('/{id}', name: 'delete', requirements: ['id' => '\d+'], methods: ['DELETE'])]
    public function delete(int $id): JsonResponse
    {
        $this->userService->delete($id);
        return $this->respondNoContent();
    }
}

A DTO carries both validation rules and the OpenAPI schema at the same time:

#[OA\Schema(description: 'Create user payload', required: ['email', 'name'])]
final readonly class CreateUserDto
{
    public function __construct(
        #[Assert\NotBlank]
        #[Assert\Email]
        #[Assert\Length(max: 180)]
        #[OA\Property(example: 'user@example.com')]
        public string $email,

        #[Assert\NotBlank]
        #[Assert\Length(min: 1, max: 100)]
        #[OA\Property(example: 'Mr. Author')]
        public string $name,
    ) {}
}

If the email is invalid, #[MapRequestPayload] throws a ValidationFailedException on its own, ExceptionListener catches it and returns a 422 with the list of violations. The controller knows nothing about this.

Alternatives

There are not many direct bundle-level equivalents; developers usually solve the same problems manually or through separate packages.

API Platform is the most obvious neighbor. A powerful framework for resource-based APIs with auto-generated endpoints, JSONAPI/Hydra/OpenAPI out of the box. But it's a completely different scale: it imposes a specific architectural approach, requires adapters, and is not a fit for every project. ApiKit is a tool for those who want to write regular controllers — just cleaner.

FOSRestBundle was historically popular for REST in Symfony, but active development has slowed down, and its use with Symfony 7+ is no longer straightforward.

Handwritten base controllers and ExceptionListener — the most common path. Most teams end up writing exactly what ApiKit does, just every time from scratch and slightly differently.

league/fractal or spatie/laravel-* — the Laravel ecosystem, not applicable to Symfony.

File and Media Uploads

#[MapRequestPayload] works with JSON and form-data, but it cannot resolve UploadedFile — that's the job of a different attribute. As of Symfony 7.1, there is #[MapUploadedFile] for files, and it fits naturally into the same slim-controller pattern. File validation is described directly in the attribute using standard Symfony constraints — Assert\Image or Assert\Video (added in 7.4, requires ffprobe on the server — installed via apt install ffmpeg).

#[Route('/{id}/avatar', name: 'upload_avatar', requirements: ['id' => '\d+'], methods: ['POST'])]
public function uploadAvatar(
    int $id,
    #[MapUploadedFile([
        new Assert\NotNull(message: 'Avatar file is required'),
        new Assert\Image(
            maxSize: '5M',
            mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
            mimeTypesMessage: 'Only JPEG, PNG and WebP images are allowed',
            maxWidth: 2048,
            maxHeight: 2048,
        ),
    ])]
    UploadedFile $avatar,
): JsonResponse {
    return $this->respondSuccess(
        UserResponseDto::fromEntity($this->userService->updateAvatar($id, $avatar))
    );
}

If a constraint is violated, #[MapUploadedFile] throws an HttpException, which ExceptionListener already intercepts and converts into a standard 422 response — no extra code needed in the controller.

For video the pattern is identical — extract it into a separate controller:

#[Route('/api/media', name: 'api_media_')]
final class MediaController extends AbstractApiController
{
    public function __construct(
        private readonly FileUploader $fileUploader,
    ) {}

    #[Route('/video', name: 'upload_video', methods: ['POST'])]
    public function uploadVideo(
        #[MapUploadedFile([
            new Assert\NotNull(message: 'Video file is required'),
            new Assert\Video(
                maxSize: '100M',
                mimeTypes: ['video/mp4', 'video/webm'],
                maxWidth: 1920,
                maxHeight: 1080,
                mimeTypesMessage: 'Only MP4 and WebM videos are allowed',
            ),
        ])]
        UploadedFile $video,
    ): JsonResponse {
        $path = $this->fileUploader->upload($video, 'videos');

        return $this->respondSuccess([
            'path'         => $path,
            'originalName' => $video->getClientOriginalName(),
            'size'         => $video->getSize(),
            'mimeType'     => $video->getMimeType(),
        ]);
    }
}

If you need to accept both JSON fields and a file in a single request (multipart/form-data), both attributes can be combined in the method signature — they are validated independently, and any violation produces a 422:

#[Route('', name: 'create', methods: ['POST'])]
public function create(
    #[MapRequestPayload] CreatePostDto $dto,
    #[MapUploadedFile([
        new Assert\Image(
            maxSize: '2M',
            mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
        ),
    ])]
    ?UploadedFile $thumbnail = null,
): JsonResponse {
    return $this->respondCreated(
        PostResponseDto::fromEntity($this->postService->create($dto, $thumbnail))
    );
}

Assert\Image and Assert\Video have nothing to do with the bundle itself — they are standard Symfony constraints, and ExceptionListener simply intercepts violations regardless of what triggered them.

Supported Architectures

Classic MVC / service layer — an ideal fit. Controller → Service → Repository. ApiKit was written exactly for this scenario.

Hexagonal Architecture (Ports & Adapters) — pairs well. The controller stays a thin input adapter, the DTO serves as a port. ApiException can be thrown from any Application service layer.

CQRS — works without restrictions. The controller maps a DTO into a Command/Query and passes it to the bus. The response is the result of a Handler, wrapped with respondSuccess.

DDD — works correctly, including strict layer isolation. More details in the next section.

Microservices — a great choice for small services that need a consistent API without the overhead of API Platform.

Vertical Slice Architecture (VSA) — pairs nicely. Each slice is a vertical cut for a specific feature (CreateUser, UploadAvatar, PublishPost) with its own controller, DTO, and handler. The bundle does not know how the code is organized and places no constraints on directory structure. An invokable controller slice looks natural:

// src/Features/CreateUser/CreateUserController.php
final class CreateUserController extends AbstractApiController
{
    public function __construct(
        private readonly CreateUserHandler $handler,
    ) {}

    #[Route('/api/users', methods: ['POST'])]
    public function __invoke(#[MapRequestPayload] CreateUserInput $input): JsonResponse
    {
        return $this->respondCreated($this->handler->handle($input));
    }
}

ApiException is thrown from the handler, ExceptionListener catches it globally — each slice is written independently, but the external API contract stays unified.

Modular monolith — each module can use ApiControllerTrait independently, and the response format will be consistent across the entire application.

EntityExists in DDD Projects

A classic question when using the bundle in DDD projects: does EntityExists violate the isolation of the domain layer? No — the architecture is built around a port.

The #[EntityExists] constraint and EntityExistsValidator depend only on EntityExistenceCheckerInterface. All Doctrine interaction is isolated in DoctrineEntityExistenceChecker at the infrastructure level.

How the bundle registers the Doctrine implementation. Precision matters here — simply checking whether the package is installed is not enough. doctrine/orm may exist in vendor (e.g. as require-dev) while DoctrineBundle is not configured and EntityManagerInterface is therefore absent from the container. Autowiring would then fail with an error on cache:clear.

The bundle handles this with a two-level check:

ApiKitExtension registers definitions only if interface_exists('Doctrine\ORM\EntityManagerInterface') — a string check, to avoid creating a static class reference and triggering "Undefined class" from PHPStan in projects without Doctrine.
RegisterDoctrineCheckerPass runs later, after the container is compiled, and checks $container->has('doctrine.orm.entity_manager'). If the service is absent — it removes the definitions for DoctrineEntityExistenceChecker, EntityExistsValidator, and the interface alias. This guards against the "package installed but DoctrineBundle not configured" scenario.

The result: the bundle works correctly in any configuration — with Doctrine, without Doctrine, and in the in-between state.

Custom persistence backend. In projects using a different ORM or a non-standard persistence layer, you can register your own implementation:

// Infrastructure/Persistence/CustomEntityExistenceChecker.php
final class CustomEntityExistenceChecker implements EntityExistenceCheckerInterface
{
    public function __construct(
        private readonly MyRepositoryRegistry $registry,
    ) {}

    public function exists(string $entityClass, mixed $value, string $field = 'id'): bool
    {
        return $this->registry->for($entityClass)->existsBy($field, $value);
    }
}

# config/services.yaml
services:
    ApiKit\Validator\Constraint\EntityExistenceCheckerInterface:
        alias: App\Infrastructure\Persistence\CustomEntityExistenceChecker

The #[EntityExists] constraint stays in the Application or Domain layer — it knows nothing about Doctrine or any specific storage. All database work is isolated in the infrastructure layer, as it should be.

One separate note — performance: every EntityExists on a DTO field means a separate SELECT. When validating multiple such fields, queries run sequentially. For most use cases this is negligible, but it's worth keeping in mind for high-load endpoints.

Installation and Configuration

composer require bulatronic/api-kit

The bundle is available on Packagist. Requires PHP 8.2+ and Symfony ^7.4|^8.0. When installed via Composer, the bundle registers itself automatically. A recipe for Symfony Flex has been submitted to symfony/recipes-contrib. Once approved, the config/packages/api_kit.yaml configuration file will be created automatically. Until then, create it manually if needed — all values have sensible defaults and the file is not required:

# config/packages/api_kit.yaml
api_kit:
  response:
    include_timestamp: true
    pretty_print: '%kernel.debug%'
  exception_handling:
    log_errors: true
    show_trace: '%kernel.debug%'
  validation:
    translate_messages: true

If your controller does not extend any base class — extend AbstractApiController:

final class UserController extends AbstractApiController
{
    #[Route('/api/users', methods: ['GET'])]
    public function list(): JsonResponse
    {
        return $this->respondSuccess($this->userService->findAll());
    }
}

If you already have your own inheritance hierarchy — add the trait directly:

// Already extending another base class — just add the trait
class MyController extends MyBaseController
{
    use ApiControllerTrait;
}

Both options give you the same set of methods: respondSuccess, respondCreated, respondNoContent, respondError, respondNotFound, respondForbidden, respondUnauthorized.

Open Source

The bundle is open source. You are free to use it, modify it, and adapt it to your own projects. If a feature is missing, behavior differs from what you expected, or you have an improvement idea — feel free to open an issue or send a PR. If the tool proved useful, a GitHub star is the best currency and motivation.

Summary

ApiKit solves a boring but important problem: it removes boilerplate from controllers, guarantees API consistency, and gives the team a shared language for errors and responses. It does not impose an architecture, does not pull in unnecessary dependencies, and integrates into any Symfony project in a few minutes.

The scenarios where it delivers the most value are projects with multiple developers where consistency matters, and APIs for mobile apps or SPAs where the frontend relies on a predictable response structure.

GitHub: bulatronic/api-kit
Packagist: bulatronic/api-kit

Symfony Init - Fast Project Bootstrap Without the Boilerplate

Dev — Sat, 21 Feb 2026 18:06:59 +0000

Every time I wanted to quickly try something with Symfony, the same story repeated itself: spin up a PHP-FPM or FrankenPHP container, exec into it, install symfony/skeleton, configure Nginx or a Caddyfile, set environment variables... All that before writing a single line of actual code.

DI container, console commands, component-based architecture... It's no secret that Symfony is heavily inspired by the Java ecosystem. So why not try to build something similar to start.spring.io?

That's how pet project https://symfony-init.dev was born.

What the User Gets

You choose the parameters on the website:

PHP: 8.3, 8.4, 8.5 (parsed from php.net in real time)
Server: PHP-FPM + Nginx or FrankenPHP
Symfony: latest versions (parsed from symfony.com in real time)
Database: PostgreSQL, MySQL, MariaDB, SQLite, or none
Cache: Redis or Memcached
Extensions: Doctrine ORM, Security, Mailer, Messenger, Validator, Serializer, API Platform, HTTP Client, Nelmio API Doc
Message broker: RabbitMQ

Click "Generate" - and you get a ZIP archive with a fully working project. Inside: Symfony, docker-compose.yml, Dockerfile, web server config, and a preconfigured .env.

Run a single command:

docker compose up -d --build

That's it.

The Service Stack

Ironically, the service itself is built with Symfony 7.4, runs on FrankenPHP, and is formatted with PHP CS Fixer using the @Symfony rule set.

How It Works Internally

Project Generation

The core class is ProjectBuilder. It performs the following steps:

Runs composer create-project symfony/skeleton with --no-install
Generates Dockerfile, docker-compose.yml, and web server config via Twig
Patches composer.json to set the required PHP version
Installs selected packages using composer require
Runs composer install --optimize-autoloader
Cleans up Docker blocks automatically added by Symfony Flex

The last step is an important nuance. Symfony Flex injects###>bundle### blocks into docker-compose.yml when installing certain packages. To avoid duplicating services (postgres, redis, etc.), generation runs with SYMFONY_SKIP_DOCKER=1, and any leftovers are removed using a regex:

$content = preg_replace('/\n*###>.*?###.*?\n.*?###<.*?###.*?\n*/s', "\n", $content);

Extensions are implemented using Symfony's tagging system. Each extension is a separate class tagged as app.extension. ExtensionRegistry collects them via #[TaggedIterator] and resolves dependency graphs. For example, if you select API Platform, Doctrine ORM, Serializer, and Nelmio API Doc are automatically included.

Caching

The most interesting architectural decision is filesystem-based caching.

Each combination of parameters (PHP × Symfony × server × extensions × database × cache × RabbitMQ) is converted into a stable cache key:

public function cacheKey(): string
{
    $ext = $this->extensions;
    sort($ext);

    return sprintf(
        'project_%s_%s_%s_%s_%s_%s_%s',
        $this->phpVersion,
        $this->server,
        $this->symfonyVersion,
        implode('_', $ext),
        $this->database ?? 'none',
        $this->cache ?? 'nocache',
        $this->rabbitmq ? 'rabbitmq' : 'norabbitmq'
    );
}

The project name is intentionally excluded from the key - it only affects the folder name inside the archive, not the file contents. This allows multiple users with identical stacks to reuse the same generated project.

When a request comes in, the service checks the cache. If a match is found, it reuses the existing directory and packages it into a ZIP with the user's chosen project name. If not, it performs a full build, stores the result in var/share/projects/, and returns the path. Cache TTL is 24 hours.

$cachedPath = $this->cache->get(
    $config->cacheKey(),
    function (ItemInterface $item) use ($config): string {
        $item->expiresAfter(self::CACHE_TTL); // 86400 sec
        return $this->buildAndCache($config);
    }
);

return $this->zipper->createZip($cachedPath, $config->projectName);

There is also a console command for cache warming:

# popular configurations only (default)
php bin/console app:warm-cache --popular-only

# all base combinations PHP × Symfony × server (no extensions/db; slower)
php bin/console app:warm-cache --all-base

Why No Redis, No Database - and Why So Simple?

A fair question. Redis is an obvious solution for caching with TTL. But here we are caching entire project directories weighing several megabytes each. Redis operates in memory - storing full project directories there would be wasteful and against its intended use.

The filesystem is the right tool for this job. Symfony Cache natively supports cache.adapter.filesystem, storing data undervar/share/pools/. No extra infrastructure. No synchronization complexity.

A database is also unnecessary. The service has no users, no history, and no relational data requirements. Adding PostgreSQL just for rate limiting or metrics would be overengineering.

The same philosophy applies to the overall architecture. FrankenPHP supports worker mode, where the PHP process persists across requests and the application boots only once. That can significantly improve performance for high-RPS applications. But in this case, the bottleneck isn't PHP - it's Composer process execution, which takes several seconds. Worker mode wouldn't help here and would introduce state management complexity between requests. Not worth it.

Horizontal scaling raises similar issues. Multiple replicas would break the filesystem cache since each container would have isolated storage. That would require a shared volume or centralized storage, adding complexity for no real benefit at the current scale. One container. One filesystem cache. Symfony Lock for synchronization. That's enough.

Why ZIP Instead of Just composer.json?

This question defines the entire value proposition.

If the service only returned a composer.json, the user would still need PHP, Composer, manual composer install, and manual server configuration. The original problem wouldn't be solved.

The real value lies in delivering a fully built project:

composer install already executed
vendor/ included
composer.lock generated
Dockerfile with correct PHP extensions
docker-compose.yml with required services
.env preconfigured with correct DSNs

The user receives a project in a state of "unzip anddocker compose up".

The composer.lock file is crucial - it locks exact dependency versions, ensuring reproducible builds. Generating it properly without actually installing packages is impossible.

Rate Limiting & Security

The /generate endpoint is protected by a rate limiter: 30 requests per hour per IP (sliding window). It's implemented via RateLimitSubscriber, an event subscriber onkernel.controller. If the limit is exceeded, it returns HTTP 429 withRetry-After and X-RateLimit-Remaining headers.

Project generation is expensive - Composer processes take seconds. Cache absorbs most traffic (popular configurations are prewarmed and returned instantly). But intentionally generating rare combinations would cause cache misses and trigger full builds each time. On a small server, that's noticeable. The rate limiter prevents such abuse.

Small Notes

The cleanupFlexDockerFiles method relies on a regex. It works, but it's fragile. If Symfony Flex changes its block format, it could silently break. At minimum, logging a warning when cleanup behaves unexpectedly would be wise.

The project name not being part of the cache key is logically correct, but it should be explicitly documented. Since composer.json contains the package name, two users with different project names will receive identical composer.json files. For a starter project generator, that's acceptable - but potentially surprising.

Final Thoughts

The service solves a very specific problem for me: eliminating boilerplate when starting a Symfony project. Every architectural decision - worker mode, scaling, Redis - was consciously rejected because it added complexity without meaningful benefit. One container. Filesystem cache. Simple lock. Sometimes the best solution is the boring one.

The service runs on a modest VPS: 1 CPU core (2.2 GHz), 0.5 GB RAM, 10 GB HDD. If it becomes unavailable or the load grows, it can always be run locally - the repository is open source: https://github.com/bulatronic/symfony-init

Try it: https://symfony-init.dev

I'd love to get feedback, ideas, and pull requests. And a star on GitHub would be greatly appreciated ⭐