letkode/common-bundle

Common exceptions, attributes, value resolvers and utilities for Symfony applications

1.2.0 2026-07-17 18:46 UTC

Requires

• php: ^8.4
• doctrine/persistence: ^3.0 || ^4.0
• letkode/helpers-bundle: ^1.0
• symfony/http-foundation: ^7.0 || ^8.0
• symfony/http-kernel: ^7.0 || ^8.0
• symfony/translation-contracts: ^3.0
• symfony/uid: ^7.0 || ^8.0
• symfony/validator: ^7.0 || ^8.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.95
• phpstan/phpstan: ^2
• phpunit/phpunit: ^11

MIT

Published on Packagist.org on 2026-07-17 18:48 UTC

README

Common exceptions, attributes, value resolvers and utilities for Symfony applications.

Installation

composer require letkode/common-bundle

Symfony Flex will register the bundle automatically. If not using Flex, add it manually:

// config/bundles.php
return [
    Letkode\CommonBundle\LetkodeCommonBundle::class => ['all' => true],
];

Contents

Exceptions

All exceptions implement HttpStatusExceptionInterface and map directly to an HTTP status code. Throw them from services — the ExceptionListener in your project converts them to JSON responses.

Class	HTTP
BadRequestException	400
UnauthorizedException	401
EntityNotFoundException	404
TooManyRequestsException	429
ValueObjectException	422

throw new EntityNotFoundException('User not found.');
throw new ValueObjectException('Invalid email.', translationKey: 'errors.email_invalid');

Attributes

#[UniqueField] — Constraint

Validates that a field value is unique in the database via Doctrine.

#[UniqueField(entityClass: User::class, field: 'email')]
public string $email;

Use scopes to narrow the lookup and/or exclude the record being edited from the check. Each UniqueFieldScope resolves a value from a route param or a sibling property, then either Filters the query (via an association) or Excludes a match from the violation:

// Update DTO: same email is fine if it's still the record at /users/{uuid}
#[UniqueField(
    entityClass: User::class,
    field: 'email',
    scopes: [new UniqueFieldScope('uuid', UniqueFieldScopeSource::RouteParam, 'uuid', UniqueFieldScopeMode::Exclude)],
)]
public string $email;

// Create DTO: email only needs to be unique within the tenant from /tenants/{tenantUuid}/contacts
#[UniqueField(
    entityClass: TenantContact::class,
    field: 'email',
    scopes: [new UniqueFieldScope('tenant', UniqueFieldScopeSource::RouteParam, 'tenantUuid', scopeEntityClass: Tenant::class)],
)]
public string $email;

#[MapUuid] — Mapping

Marks a constructor parameter or property for automatic UUID deserialization.

Value Resolver

UuidValueResolver

Automatically resolves Uuid typed route parameters without manual conversion.

#[Route('/users/{uuid}')]
public function show(Uuid $uuid): JsonResponse { ... }

Utils

BuilderUrlClient

Builds absolute URLs using the configured APP_CLIENT_URL base. Requires letkode/helpers-bundle.

JsonReader

Reads and decodes JSON files from the filesystem, throwing on invalid JSON.

Requirements

• PHP ^8.4
• Symfony ^7.0 || ^8.0
• doctrine/persistence ^3.0
• letkode/helpers-bundle ^1.0

License

MIT — see LICENSE.