Getting Started

Know what this is before you install it. pugx/shortid-doctrine-bundle is a Symfony bundle. It wires up the shortid Doctrine DBAL type from pugx/shortid-doctrine (a Hashids-backed encoder) via Symfony's DI container. There is no Laravel service provider, no facade, no publishable config — composer require on a stock Laravel app gets you a package that does nothing.
If you're on Eloquent, skip it. Reach for hashids/hashids (or sqids/sqids) directly and do the encode/decode in an accessor or a cast. That covers the entire feature set of this package in ~15 lines with no Doctrine dependency.
If you're on Laravel + Doctrine (laravel-doctrine/orm, or a hybrid app), install only pugx/shortid-doctrine — not the bundle — and register the type yourself in a service provider's boot():
```
Type::addType('shortid', \PUGX\Shortid\Doctrine\ShortIdType::class);
```
First use case: opaque public identifiers. Column mapped as type: 'shortid', generated on insert, so URLs and API payloads carry aB3xK9 instead of 1042.
Where to look first: the bundle's config tree (salt, alphabet, min length) to see what knobs exist, and ShortIdType::convertToPHPValue() to understand that hydration hands you a value object, not a string. That single detail drives most of the friction below.

Implementation Patterns

Entity mapping. Mark the column type="shortid" and pair it with a custom id generator (#[ORM\GeneratedValue(strategy: 'CUSTOM')] + #[ORM\CustomIdGenerator(...)]), or assign in the constructor/prePersist. The custom-generator route is cleaner because it guarantees the id exists before any flush-time listener runs.
Treat the id as a value object everywhere. Hydration returns ShortId, so (string) $entity->getId() at the serialization boundary, and implement JsonSerializable on the entity (or use a normalizer) so toArray() doesn't emit an object graph.
Repository lookups need the type. find($shortString) and ->where('id', $shortString) bind as a plain string; comparisons work because the column is physically a varchar, but you bypass the type's validation and can silently match garbage. Wrap explicitly with ->setParameter('id', $short, 'shortid') when correctness matters.
Route binding is DIY in Laravel. Symfony's ParamConverter handles shortid for free; on Laravel you write a Route::bind('user', fn ($v) => User::find($v) ?? abort(404)) or resolveRouteBinding() in the model. One place, do it once.
Salt comes from env, per environment. Production and staging must not share a salt. Keep it in config/ sourced from .env, never committed.

Changing the salt is a data migration, not a config tweak. Every existing id re-encodes to something different. Plan it like a schema change.
Hashids is obfuscation, not encryption. Given the salt, ids are fully reversible. Don't put secrets in them and don't treat an unguessable id as authorization — still check ownership on every request.
Registration order matters. Type::addType() must run before Doctrine builds metadata. Registering in a queued job, an artisan command, or a package provider that loads late will produce "Unknown column type shortid" only in those contexts — a classic intermittent bug. Put it in a provider that's always booted.
v1.3.1 (Symfony 8 deprecation fix, PR #19) is a no-op for Laravel users. Signature-only fix, no API or behavior change, and the bundle's DI code path never executes outside Symfony. If you pinned v1.3.0 against Symfony 8 you were only seeing deprecation notices; the underlying pugx/shortid-doctrine type is unchanged.
Extension points: subclass the DBAL type to override the encoder, or swap in your own generator service if you want Sqids instead of Hashids while keeping the column mapping. The type is thin — forking behaviour is cheaper than fighting it.
Debugging: in tinker, Doctrine\DBAL\Types\Type::hasType('shortid') tells you instantly whether the provider ran. If that's false, no amount of entity annotation debugging will help.