README

ChamberOrchestra Form Bundle

A Symfony 8 bundle that simplifies JSON-first form handling for REST APIs. It provides controller traits for the submit/validate/response flow, specialized API form types with CSRF disabled, reusable data transformers, Doctrine-backed uniqueness validation, and structured error responses following RFC 9457 (Problem Details for HTTP APIs).

Features

• Controller traits (FormTrait, ApiFormTrait) for submit/validate/response flow with null-safe request handling
• JSON payload handling for mutation requests with automatic merging of uploaded files
• API form base types (QueryForm, MutationForm) with CSRF disabled and empty block prefixes for clean JSON payloads
• Custom form types: BooleanType, TimestampType, HiddenEntityType with secure query builder parameterization
• Data transformers for booleans, Unix timestamps, comma-separated arrays, and JSON strings
• RFC 9457 problem details via ValidationFailedView with structured violations for consistent API error responses
• Translatable error normalizer (ProblemNormalizer) for localized exception messages in problem detail responses
• UniqueField validation constraint for Doctrine repositories with multi-field checks, closure-based exclusions, and custom normalizers
• TelExtension to strip non-digit characters from phone number input
• CollectionUtils for syncing Doctrine collections (add new / remove stale items)

Requirements

• PHP ^8.5
• Symfony 8.0 components (framework-bundle, form, validator, config, dependency-injection, runtime, translation, clock)
• Doctrine ORM 3.6
• chamber-orchestra/view-bundle 8.0

Installation

composer require chamber-orchestra/form-bundle:8.0.*

Enable the bundle in config/bundles.php:

return [
    // ...
    ChamberOrchestra\FormBundle\ChamberOrchestraFormBundle::class => ['all' => true],
];

Usage

Controller Traits

Use FormTrait for standard HTML form submissions and ApiFormTrait for JSON API endpoints.

handleFormCall() accepts a form class or instance, handles the request, and returns a view or response. handleApiCall() does the same for API endpoints -- it automatically parses JSON payloads for MutationForm types and merges uploaded files.

onFormSubmitted() checks validity, returns a ValidationFailedView on failure, or invokes the callback on success:

use ChamberOrchestra\FormBundle\ApiFormTrait;
use ChamberOrchestra\ViewBundle\View\ViewInterface;
use Symfony\Component\HttpFoundation\Request;

final class SearchCourseAction
{
    use ApiFormTrait;

    public function __invoke(Request $request): ViewInterface
    {
        $form = $this->createForm(SearchCourseForm::class);
        $form->submit($request->query->all());

        return $this->onFormSubmitted($form, function (SearchCourseData $dto) use ($request) {
            $entities = $this->er->searchCourses(
                $pagination = $this->getPagination(['per_page_limit' => $this->getPerPageLimit($request)]),
                $dto->query,
                $dto->brands,
                $dto->topics,
                $dto->products,
                $dto->durations
            );

            return new PaginatedView($entities, $pagination, CourseView::class);
        });
    }
}

API Form Types

Extend QueryForm for GET requests or MutationForm for POST/PUT/PATCH requests. Both disable CSRF protection and use empty block prefixes for clean JSON input/output.

Data Transformers

HiddenEntityType

Loads Doctrine entities by ID from a hidden form field. Supports a custom query_builder option with secure parameterized queries.

UniqueField Validator

Validates field uniqueness against Doctrine repositories. Supports multiple fields, closure-based exclusions, custom normalizers, and targeted error paths.

ProblemNormalizer

Extends Symfony's ProblemNormalizer to translate exception messages when the exception implements TranslatableExceptionInterface. This ensures localized error messages in RFC 9457 problem detail responses.

Response Views

Testing

Install dependencies and run the full test suite:

composer install
./vendor/bin/phpunit

The integration test kernel (tests/Integrational/TestKernel.php) boots a minimal Symfony application with in-memory SQLite for Doctrine tests.

License

MIT