Uuid Bundle Laravel Package

Getting Started

Verdict first: this is a Symfony 2 bundle, archived, with 2 stars and zero dependents. It is not a Laravel package, has no service provider, no facade, and no package auto-discovery. For a Laravel codebase the correct first step is almost always to not install it and use ramsey/uuid or Laravel's built-in Str::uuid() / HasUuids trait instead. The value here is as a reference for how to wire a UUID generator and Doctrine type into a container, not as a runtime dependency.

If you are auditing or maintaining a legacy Symfony 2 app that already uses it:

• Read composer.json first. It will declare the Symfony 2 constraint and the underlying kherge/uuid library it wraps; that underlying library is where the actual generation logic lives.
• Look next at DependencyInjection/ and Resources/config/services.xml. That is where the service IDs, generator wiring, and any Doctrine DBAL type registration are defined. Do not guess service IDs — dump them.
• Check for a Doctrine/, Types/, Twig/, or Command/ directory to see whether the bundle ships a DBAL type, a Twig filter, or a console command.

Minimal Symfony 2 registration:

// app/AppKernel.php
public function registerBundles()
{
    $bundles = array(
        // ...
        new Kherge\UuidBundle\KhergeUuidBundle(),
    );
    return $bundles;
}

Then confirm what actually got registered:

php app/console container:debug | grep -i uuid
php app/console container:debug kherge_uuid.generator   # adjust to the real ID

The first useful use case is: inject the bundle's generator into one of your services and assign a UUID to an entity ID before flush, so identifiers exist prior to persistence (important for event dispatching, URLs, and client-side correlation).

Implementation Patterns

Constructor injection, not container pulls. In Symfony 2, declare the dependency in services.yml and inject it. This also makes the code portable if you later migrate off the bundle.

services:
    app.registration:
        class: AppBundle\Service\Registration
        arguments: ['@kherge_uuid.generator']   # verify the actual ID with container:debug

Generate before persist. Prefer assigning the ID in the entity constructor or a prePersist lifecycle callback rather than relying on a database default. This means the object has a stable identity through the whole request:

public function __construct()
{
    $this->id = $generator->generate(); // or whatever the bundle exposes
}

Doctrine mapping. If the bundle ships a DBAL type, map it explicitly; otherwise fall back to a 36-character string:

# config.yml (Symfony 2)
doctrine:
    dbal:
        types:
            uuid: Kherge\UuidBundle\Doctrine\Type\UuidType  # confirm the class exists

/** @ORM\Id @ORM\Column(type="uuid") */
protected $id;

Prefer binary(16) storage if the type supports it; use char(36) if you need human-readable rows in ad-hoc queries and can afford the index size.

Bridging into Laravel (only if you are porting a legacy app). Do not try to register the Symfony bundle. Bind the underlying generator yourself:

// app/Providers/UuidServiceProvider.php
$this->app->singleton(UuidGenerator::class, function () {
    return new UuidGenerator(); // the kherge/uuid class, not the bundle
});

// If you need Doctrine DBAL type support alongside Eloquent:
if (! Type::hasType('uuid')) {
    Type::addType('uuid', UuidType::class);
}

Testing. Bind a fake or seeded generator in the test container and assert the ID format (^[0-9a-f]{8}-...$) rather than a specific value. If you need deterministic IDs, inject a stub that returns a fixed sequence.

Modern Laravel equivalents — these are what you should reach for in new code:

use Illuminate\Support\Str;

$id = (string) Str::uuid();          // v4
$id = (string) Str::orderedUuid();   // time-ordered, better index locality

use Illuminate\Database\Eloquent\Concerns\HasUuids;

class Order extends Model
{
    use HasUuids; // Laravel 9+
}

Gotchas and Tips

• Abandoned and EOL. Symfony 2 reached end of life in 2018; the bundle is archived and receives no security or compatibility fixes. On PHP 8+, composer require will likely fail on platform constraints — resist --ignore-platform-reqs in production.
• Autoloading. Symfony 2-era bundles often use PSR-0. Composer 2 deprecates it; you may need a classmap entry to get classes loading at all.
• No Laravel auto-discovery. Kherge\UuidBundle\KhergeUuidBundle is not an Illuminate\Support\ServiceProvider. Adding it to config/app.php will simply fatal. There is nothing to php artisan vendor:publish.
• Service visibility. In Symfony 2.8+, services default to private. If $container->get('...uuid...') throws, that is expected — inject instead, or use container:debug --show-private to confirm the ID exists.
• Binary UUID hydration. If a DBAL type is present, verify both convertToDatabaseValue and convertToPHPValue. A half-implemented type returns raw bytes from MySQL and produces garbage-looking strings or resource warnings in var_dump.
• Index locality. UUID v4 is random; as a primary key it fragments B-tree indexes at scale. Prefer ordered UUIDs (v1/v6/v7) or ULIDs. If this bundle only offers v4, that is a real production limitation, not a detail.
• Storage sizing. char(36) in utf8mb4 costs up to 144 bytes per index entry. binary(16) is four times smaller; convert at the boundary, not in queries. Normalize case (lowercase) before comparison — UUIDs are case-insensitive but string indexes are not.
• Debugging tips. Use php app/console debug:container <id> (2.8+), container:debug, and debug:config kherge_uuid if a configuration tree exists. When in doubt, read DependencyInjection/Configuration.php and ...Extension.php — that is the ground truth for config keys and service wiring.
• Extension points. You can decorate the generator, override Resources/config/services.xml via a compiler pass, or define your own DBAL type and ignore the bundle's. Given the maintenance status, copying the ~100 lines of wiring into your own bundle or service provider is usually safer than depending on it.
• Do not adopt for new work. For Laravel: ramsey/uuid plus ramsey/uuid-doctrine if you use Doctrine, or native Str::uuid() / HasUuids if you use Eloquent. Both are maintained, tested on current PHP, and have real community support.