Download the PHP package leads/core without Composer

leads/core

Shared core bundle for Leads projects built on the Symfony Framework. It provides HTTP payload mapping into request DTOs, DBAL-based pagination, API request validation helpers and base controller utilities.

Requirements

• PHP >= 8.4
• Symfony 8.1+
• Doctrine DBAL ^4.0 (used by the pagination component)

Installation

Register the bundle in config/bundles.php (done automatically if you use Symfony Flex):

HTTP payload mapping

Leads\Core\Payload maps an HTTP request into an immutable request DTO declared with attributes — no serializer, no per-endpoint glue code. Put #[Payload] on a controller argument and the bundle's value resolver builds, casts and validates the DTO:

Every constructor parameter declares its source: #[FromBody], #[FromQuery], #[FromPath] or #[FromHeader('Name')]. Values are cast to the parameter type (scalars, \DateTimeImmutable, backed enums, nested DTOs, collections via a @param list<...> docblock) and then run through the Symfony Validator (constraint attributes on the DTO). Additional behavior attributes:

• #[HttpPayload(groups: [...], maxBodyBytes: ...)] (class level) — validation groups and body size limit
• #[Clamp(min, max)] — clamp an int into a range
• #[FallbackTo(value)] — value to use when casting fails (except type mismatches)
• #[Split(separator: ',')] — split a query string into a scalar list
• #[MaxItems(n)] — collection size limit (default 1000)
• #[FreeForm] — accept an arbitrary array structure as-is
• #[Normalized] — case-insensitive enum matching

Misconfiguration (missing source attribute, unsupported type, nested constraints without #[Assert\Valid], …) fails fast with a \LogicException when the plan is compiled — not at request time.

Errors are reported per field with JSON-pointer-style paths (body/items/0/quantity, query/limit): casting failures throw a 400, validator violations a 422, plus 413 for oversized and 400 for malformed bodies. All of these implement Leads\Core\Payload\Error\HttpProblemException, and the bundled PayloadExceptionListener turns them into RFC 9457 application/problem+json responses automatically. StateConflictException (409) is available for domain-level conflicts in the same format.

The component is extensible from the consuming project: implement Leads\Core\Payload\Cast\ValueCaster or Leads\Core\Payload\Source\ValueSource in your application and autoconfiguration tags it (leads_core.payload.caster / leads_core.payload.source) — no configuration needed.

You can also call the mapper directly instead of using the resolver: inject Leads\Core\Payload\PayloadMapper and call map(MyRequest::class, $request).

Pagination

Page-based pagination over a Doctrine DBAL QueryBuilder. The Leads\Core\Pagination namespace is excluded from container autowiring — instantiate the classes manually:

paginate() returns a ListResponseDTO:

• items — the rows for the requested page (fetchAllAssociative() result)
• pagination — a PaginationDTO with count (items on this page), total (total rows), page, perPage and pages (total page count)

The total is computed by wrapping your query in a COUNT(*) subquery (with ORDER BY stripped), so it stays correct for queries with GROUP BY or DISTINCT. Pagination throws \InvalidArgumentException if page or perPage is less than 1.

To paginate a different data source, implement Leads\Core\Pagination\PaginationInterface (getItems(int $offset, int $limit): array and getTotal(): int) and pass it instead of DBALPagination.

ClickHouse

ClickHousePagination runs the same DBAL QueryBuilder-built query against ClickHouse via the smi2/phpclickhouse client. The package is an optional dependency — install it in your project first:

Constraints:

• The QueryBuilder must use named parameters (:name) — positional ? placeholders are not substituted by the ClickHouse client.
• The SQL (including LIMIT/OFFSET syntax and identifier quoting) is rendered by the DBAL platform of the connection the QueryBuilder was created from, so use a connection whose platform produces ClickHouse-compatible SQL (MySQL and PostgreSQL platforms are fine).

API validation and base controller

ApiValidator wraps the Symfony Validator: it validates an object against its constraint attributes and throws ApiValidationException if there are violations. The exception exposes the violations as getErrors() — a list of ['property' => ..., 'message' => ...] pairs, also JSON-encoded into the exception message.

Controllers can extend BaseAction to get validation plus JSON response helpers:

Available response helpers:

• create200Response(array $data) — 200 with a JSON body
• create201Response(string $id) — 201 with {"id": ...}
• create201ContentResponse(array $response) — 201 with a custom body
• create201EmptyResponse() — 201 with an empty body
• create204Response() — 204
• create400Response(string $message) — 400 with a message
• createCustomResponse(array $data, int $status) — any status

ApiValidatorInterface is autowired to ApiValidator by the bundle; you can also inject it directly into your own services.

Exceptions

The Leads\Core\Exception namespace provides ready-to-use domain exceptions. All of them extend \RuntimeException and carry an HTTP-like status code in getCode(), so an exception listener can map them to responses directly. Each constructor accepts an optional custom message, code override and previous throwable:

• Leads\Core\Exception\EntityNotFoundException — Entity not found., code 404; for missing entities in repositories/handlers
• Leads\Core\Exception\UserNotFoundException — User not found., code 404
• Leads\Core\Exception\AccessDeniedException — Access Denied., code 403

License

MIT