Download the PHP package bulatronic/api-kit without Composer
On this page you can find all versions of the php package bulatronic/api-kit. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download bulatronic/api-kit
More information about bulatronic/api-kit
Files in bulatronic/api-kit
Package api-kit
Short Description Lightweight Symfony bundle for building REST APIs with DTO-first validation, standardized responses, and thin controllers
License MIT
Informations about the package api-kit
ApiKit Symfony Bundle
A minimalist Symfony Bundle for building REST APIs with standardized responses, automatic exception handling, and DTO validation.
Key Features
- Standardized JSON responses — unified format for all endpoints
- Automatic exception handling — exceptions become JSON without
try/catchin controllers ApiException— throw structured errors with details from anywhere in the codebase- DTO validation — uses native Symfony
#[MapRequestPayload]/#[MapQueryString] EntityExistsvalidator — check entity existence directly in DTO- File uploads —
#[MapUploadedFile]with automatic validation error handling (images, videos, mixed multipart) AbstractApiController+ApiControllerTrait— convenient response helpers- PHP 8.2 + Symfony 7.4 — modern features, minimal dependencies
Architecture Compatibility
ApiKit only standardizes the HTTP layer — responses and exception handling. It has no opinion on how the rest of your application is organized.
| Architecture | How ApiKit fits |
|---|---|
| Layered / Traditional | Controller → Service → Repository. Controllers use AbstractApiController, services throw exceptions. |
| DDD | ApiKit lives in the infrastructure/presentation layer. The domain knows nothing about it — domain services throw standard PHP exceptions, ExceptionListener catches them outside. |
| Hexagonal (Ports & Adapters) | AbstractApiController is a driving adapter. The application core (ports + domain) has zero dependency on ApiKit. |
| Vertical Slice Architecture | ApiControllerTrait is the natural fit — each slice is an independent class with no shared inheritance. The trait adds respond* methods without forcing a class hierarchy. |
Before & After
Without ApiKit — boilerplate in every controller:
With ApiKit — one line, same result:
Validation, exception handling, and logging are handled automatically and uniformly across all endpoints.
Installation
The bundle is automatically registered via Symfony Flex.
Quick Start
1. Create a DTO
2. Create a Controller
Two options — pick one:
Option A: extend AbstractApiController (simplest, when you don't extend another class):
Option B: use ApiControllerTrait (when you already extend another class):
3. Throw Errors from Services — No try/catch Needed
ExceptionListener catches everything automatically. Your controller stays clean:
4. Standardized Response Format
Success (200):
Validation error (422) — from #[MapRequestPayload]:
ApiException error (409):
Reference
AbstractApiController / ApiControllerTrait Methods
ResponseFactory (inject as dependency)
ApiException
EntityExists Validator
Requires Doctrine ORM:
OpenAPI Documentation Attributes
Requires nelmio/api-doc-bundle + zircote/swagger-php:
Attributes that document the {success, data, meta} / {success, error} envelope in one line,
instead of hand-writing it (and getting it wrong — see docs/OPENAPI.md for
the bug this fixes):
ApiSuccessResponse, ApiCreatedResponse (201 by default), ApiNoContentResponse (204), and
ApiErrorResponse (links to ErrorEnvelope/ValidationErrorEnvelope) — full reference,
before/after examples, and how to register the envelope schemas in nelmio_api_doc.yaml:
docs/OPENAPI.md.
Exception Handling
ExceptionListener handles automatically (no try/catch in controllers needed):
| Exception | HTTP Status | Notes |
|---|---|---|
ValidationFailedException |
422 | From #[MapRequestPayload] or manual |
HttpException(*, prev: ValidationFailed) |
Same as exception | Violations extracted |
ApiException |
Configured code | getDetails() included in response |
Any HttpExceptionInterface |
Status from exception | Standard Symfony exceptions |
Any other \Throwable |
500 | Logged; trace shown in debug mode |
Configuration
Create config/packages/api_kit.yaml (optional — sensible defaults work out of the box):
Security Considerations
ApiKit standardizes the HTTP layer only — it does not authenticate, authorize, rate-limit, or sanitize anything for you. The table below is an honest account of what the bundle's code actually protects against, and what remains entirely the consuming project's responsibility.
| Risk | Protection in ApiKit's code | Residual risk (on the consumer) |
|---|---|---|
| Stack traces leaking to clients in production | show_trace defaults to '%kernel.debug%' — off unless APP_DEBUG=1 |
Misconfiguring show_trace: true in a prod environment, or leaving APP_DEBUG=1 on in prod, re-opens the leak |
| Entity internals (Doctrine proxies, hidden fields) serialized into a response | None — ApiKit has no serialization-group enforcement by design (see docs/ARCHITECTURE.md, "What's Not Included") | Passing a Doctrine entity straight to respondSuccess()/respondCreated() instead of mapping it to a response DTO; see docs/CONTROLLER-CONVENTIONS.md |
Sensitive data leaking via ApiException details |
None — getDetails() is serialized verbatim, exactly as the developer constructed it |
Throwing ApiException with secrets, internal IDs, or raw DB values in details sends them straight to the client |
| Mass assignment / over-posting via request DTOs | #[MapRequestPayload] only ever populates the properties declared on your DTO class, never an Entity directly |
A DTO that mirrors privileged Entity fields too closely (e.g. role, isAdmin) still lets a client set them — ApiKit has no field allow-listing |
Existence oracle / enumeration via EntityExists |
None — it's a convenience validator, not an authorization check | A 422 vs. no error on EntityExists(User::class) confirms whether a given ID/UUID exists; add rate limiting or avoid exposing it on sensitive fields |
| Vulnerable transitive dependencies (Doctrine, Nelmio, swagger-php) | Kept as require-dev/suggest, never require — nothing loads unless your own code references ApiKit\OpenApi\* or EntityExists |
Whatever CVEs exist in the exact versions you pick are on you — ApiKit pins broad ranges, not exact versions; run composer audit in your own project |
None of this is enforced by a scanner or a runtime guard — it's a map of where the line between "ApiKit's job" and "your job" actually sits, so you know what to check for in review instead of assuming the bundle does it for you.
Testing
Requirements
- PHP 8.2+
- Symfony 7.4+
Optional:
- Doctrine ORM — required for
EntityExistsvalidator nelmio/api-doc-bundle+zircote/swagger-php— required for theApiKit\OpenApi\Attribute\*OpenAPI attributes
Documentation
- Usage Examples
- Architecture
- Controller Conventions — codified rules for using ApiKit correctly, written to be copied into your project's AI agent instructions (
AGENTS.md/CLAUDE.md/Copilot/etc.) - OpenAPI Documentation Attributes
- Development Guide
- Contributing
For agents working on ApiKit itself (not consuming it), see AGENTS.md.
License
MIT — see LICENSE.
Author
Bulat Timerbaev — [email protected]
All versions of api-kit with dependencies
symfony/event-dispatcher Version ^7.4|^8.1.1
symfony/framework-bundle Version ^7.4|^8.1.1
symfony/http-foundation Version ^7.4|^8.1.1
symfony/serializer Version ^7.4|^8.1.1
symfony/validator Version ^7.4|~8.0.14