Getting Started

mcfedr/uuid-paramconverter is a small Symfony bundle, not a Laravel package. It provides three integrations for ramsey/uuid:

a ParamConverter that turns a route parameter into a Ramsey\Uuid\UuidInterface/Uuid object
a Serializer normalizer that converts UUID objects to strings and back
a Symfony Form type for UUID input

For a Laravel developer, the day-to-day relevance is limited: Laravel has no Sensio ParamConverter and no Symfony Forms. In a pure Laravel app you would normally use ramsey/uuid directly, Laravel route model binding, validation rules, and custom casts. The package is worth installing only if you are maintaining a Symfony application, using Symfony Serializer/Form components outside Laravel, or working in a mixed stack where the Symfony wiring is already present.

As of 4.2.0 the package dropped support for older PHP and Symfony versions. Before you install, check the require block in composer.json on the tag you are targeting — your PHP runtime and Symfony minor version must satisfy the new floor. If you are on an older Symfony line, stay on the 4.1.x series and do not let a composer update float you across the boundary.

composer require mcfedr/uuid-paramconverter ramsey/uuid
# Older Symfony versions only (see gotchas — verify against 4.2.0 requirements):
composer require sensio/framework-extra-bundle

return [
    // ...
    Mcfedr\UuidParamConverter\McfedrUuidParamConverterBundle::class => ['all' => true],
];

First use case — typed UUID route arguments:

use Ramsey\Uuid\UuidInterface;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;

/**
 * @ParamConverter("id", class=UuidInterface::class)
 */
public function show(UuidInterface $id): Response
{
    // $id is already a Ramsey UUID, not a string
}

Equivalent Laravel first use case, without the package:

use Ramsey\Uuid\Uuid;

Route::bind('uuid', fn (string $value) => Uuid::fromString($value));

Route::get('/orders/{uuid}', function (Uuid $uuid) {
    // ...
});

For serialization, if you are already using Symfony Serializer, the normalizer is the most reusable piece — and the part least affected by the 4.2.0 platform bump:

use Mcfedr\UuidParamConverter\Normalizer\UuidNormalizer;
use Symfony\Component\Serializer\Encoder\JsonEncoder;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\Serializer\Serializer;

$serializer = new Serializer(
    [new UuidNormalizer(), new ObjectNormalizer()],
    [new JsonEncoder()]
);

Implementation Patterns

Controller route parameters. Use the ParamConverter when a controller action receives a UUID in the URL and you want the type guarantee before the action body runs. Declare the parameter explicitly with @ParamConverter or the PHP 8 attribute form; do not assume the converter is applied just because the argument is type-hinted. This is most useful on GET /resource/{id} and DELETE /resource/{id} endpoints where an invalid UUID should fail fast.

Serializer DTOs. For API request/response DTOs with UuidInterface properties, the normalizer lets you keep UUID objects in your domain layer while JSON remains a string. Register it with a high priority so it runs before the generic object normalizer:

services:
    Mcfedr\UuidParamConverter\Normalizer\UuidNormalizer:
        tags:
            - { name: serializer.normalizer, priority: 100 }

Symfony Forms. Use UuidType for fields bound to UUID properties:

use Mcfedr\UuidParamConverter\Form\Type\UuidType;

$builder->add('id', UuidType::class, [
    'required' => false,
]);

Combine it with the Symfony Validator Uuid constraint if the form must reject malformed input with a validation message rather than a transformation exception.

Laravel equivalents. In Laravel, map each Symfony concept to a native pattern:

ParamConverter → Route::bind() or route model binding on a UUID primary key
Form type → Form Request validation with the uuid rule plus a custom cast or DTO hydrator
Normalizer → API Resource string casting or a custom CastsAttributes implementation

Example custom cast:

final class UuidCast implements CastsAttributes
{
    public function get($model, string $key, $value, array $attributes): ?UuidInterface
    {
        return $value === null ? null : Uuid::fromString($value);
    }

    public function set($model, string $key, $value, array $attributes): ?string
    {
        return $value instanceof UuidInterface ? $value->toString() : $value;
    }
}

Testing. Add functional coverage for both valid and invalid UUID inputs. On Symfony, assert the converter produces the expected 404/400 for malformed route values. On Laravel, assert a 404 from route binding and a 422 from validation. This catches the common failure mode where a UUID string is accepted by one layer but rejected by another. When upgrading to 4.2.0, treat the upgrade itself as a testable change: run the suite on the new PHP/Symfony floor before merging, and keep the previous tag installed in CI for one cycle if you maintain a mixed-version stack.

Persistence is out of scope. The package does not provide a Doctrine DBAL type. If you store UUIDs in Doctrine, use ramsey/uuid-doctrine separately. In Laravel, store the UUID as a uuid/char(36) column and cast at the application boundary.

Gotchas and Tips

4.2.0 is a breaking change shipped on a minor version. The release note is only "Drops support for older php and Symfony", but that is a platform-floor break, not a patch. Do not let a permissive constraint like ^4.0 pull it in unreviewed — pin to ~4.1.0 if you still need the old floor, or ^4.2 once your runtime is confirmed. Read the tag's composer.json rather than trusting the one-line note; the exact PHP and Symfony minimums are only stated there.
The ParamConverter dependency situation needs re-verification. Earlier releases leaned on sensio/framework-extra-bundle, which is abandoned and unavailable on modern Symfony. Whether 4.2.0 dropped or merely narrowed that dependency is not stated in the release note — run composer why sensio/framework-extra-bundle (or inspect the tag's require block) after upgrading. If older Symfony support was dropped specifically to shed that bundle, the ParamConverter may now be wired through native argument resolvers or #[MapEntity]-style attributes; check the bundle's service definitions before assuming the old annotation form still applies.
Normalizer ordering matters. If UuidNormalizer runs after ObjectNormalizer, denormalization into a UuidInterface property can fail with "failed to denormalize attribute." Tag it with a high priority or place it first in a standalone Serializer chain. Upgrade time is when this regresses silently — normalizer priority ties against other bundles' services can resolve differently after a framework bump.
The package is not a Laravel package. There is no service provider, no facade, no Laravel route integration, and no Blade/Form integration. Installing it in Laravel adds dead weight unless you are deliberately using Symfony Serializer or Forms. 4.2.0 does nothing to change this.
Parsing is permissive. Ramsey\Uuid\Uuid::fromString() accepts several formats beyond canonical hyphenated UUIDs. If your API contract requires exactly canonical UUID strings, validate with a regex or a strict parser before constructing the UUID. Note that a ramsey/uuid major bump is the other common cause of this behavior shifting — pin it alongside the bundle.
ParamConverter errors are not validation errors. A malformed route UUID typically becomes a 404 or an exception, not a friendly form error. If the endpoint is user-facing, catch and translate that behavior deliberately.
Empty form values need handling. UUID form fields often submit an empty string. Configure empty_data and required explicitly so the form produces null rather than attempting to parse ''.
Do not double-convert. If a value is already a UuidInterface, ensure your normalizer or cast does not call fromString() on it. Guard with instanceof checks.
Debugging Symfony wiring: use bin/console debug:container UuidNormalizer, bin/console debug:router, and bin/console debug:form to confirm the normalizer, route converter, and form type are actually registered. Run these immediately after the 4.2.0 upgrade — a dropped platform feature is most visible as a service that silently stops being tagged. In Laravel, use php artisan route:list to confirm route binding.
Extension points are simple. The package classes are small; if behavior is close but not exact, decorate the normalizer, extend the form type, or write a custom ParamConverter/argument resolver rather than forking. For Laravel, a custom cast and a Route::bind() callback cover nearly all daily use cases without adding a Symfony dependency — and avoid the platform-floor churn entirely.

Uuid Paramconverter Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips