Weave Code
Laravel Optimus Laravel Package
cybercog/laravel-optimus
Laravel Optimus wraps the Optimus ID obfuscation library for Laravel, letting you encode and decode integer IDs into short, URL-friendly strings. It offers a facade and helpers, Blade directives, validation rules, route model binding, and configurable settings for hiding database IDs in URLs.
Transform your internal id's to obfuscated integers based on Knuth's integer hash. Laravel wrapper for the Optimus Library by Jens Segers with multiple connections support.
Frequently asked questions about Laravel Optimus
- How do I install cybercog/laravel-optimus in a Laravel application?
- Install it with composer require cybercog/laravel-optimus. Laravel package auto-discovery registers the service provider, so no manual registration is needed on supported versions. Publish the config file and set the prime, multiplier and inverse values for each connection. There are no migrations, middleware or queue assumptions to wire up.
- How do I encode and decode IDs with Laravel Optimus in controllers and Blade views?
- The package exposes a facade and global encode/decode helpers, plus Blade directives for rendering obfuscated IDs directly in templates. It also ships validation rules so incoming encoded values can be checked in form requests before you decode them. Typical usage is calling encode on an Eloquent key when building a URL, then decoding the segment and confirming the record exists before returning a response.
- Is Laravel Optimus encryption? Can I use it to secure IDs?
- No. Optimus is reversible obfuscation based on Knuth multiplicative hashing, not encryption, and anyone holding the configured prime, multiplier and inverse can decode any ID. It only deters casual enumeration and improves URL cosmetics. Never treat an encoded ID as an access-control or authorization mechanism — keep policies and gates as the real gatekeepers.
- Does cybercog/laravel-optimus support Laravel 13 and which PHP versions are allowed?
- Version 3.13.0 adds Laravel 13 support by widening the illuminate/* constraints, and the same release line still covers earlier framework versions. That lets a single package version span a staggered upgrade without maintaining a fork. Check the composer.json PHP bounds and confirm the underlying jenssegers/optimus dependency resolves on your target framework before pinning it.
- How does multiple connection support work in Laravel Optimus?
- The published config file defines several named connections, each with its own prime, multiplier and inverse values, so you can isolate ID spaces per tenant, service or dataset. Every service or application that encodes or decodes the same IDs must share byte-identical config, otherwise round-tripping silently fails. Keep the connection definitions in a shared config source rather than duplicating them by hand.
- Can I use obfuscated IDs with Laravel route model binding?
- There is no built-in route binding integration, so you need a custom resolveRouteBinding or getRouteKey implementation on the model. Decode the route segment, verify it maps to a real record, and return null for invalid values so Laravel produces a 404 instead of a 500. Decide this deliberately up front rather than discovering it at the first failing request.
- What happens if the configured prime is smaller than my maximum ID?
- The prime must be larger than the highest ID in every table the connection is used against. If it is not, you will hit collisions or exceptions that only surface once the data grows, often long after launch. Audit current and projected row counts per table before choosing the prime values.
- Can I change the multiplier or prime later without breaking existing links?
- Changing the multiplier invalidates every previously issued encoded ID, causing link rot across emails, logs, caches, sitemaps and partner integrations. If a change is unavoidable, run a dual-read phase that accepts both legacy numeric and encoded IDs, then issue encoded IDs only, then retire numeric acceptance after a deprecation window sized to your longest-lived links. Inventory anything persisted externally before the cutover.
- How does Laravel Optimus compare to Hashids, UUIDs or signed URLs?
- Optimus keeps IDs as compact reversible integers and only changes their presentation, so no schema or primary key changes are required. Hashids solves a similar problem with a different encoding scheme, while UUIDs and ULIDs change the database key itself and ripple through indexes and relations. If you need tamper-proof rather than merely non-sequential identifiers, signed URLs are a better fit.
- Is cybercog/laravel-optimus actively maintained and safe for production?
- Release 3.13.0 is a maintenance release whose notable change is Laravel 13 support, with Docker environment and documentation updates that carry no runtime impact for consumers. No breaking changes, deprecations or config schema changes are signalled, and the package is a thin wrapper around jenssegers/optimus. Since it is a boundary utility with no database or middleware footprint, the residual risk is low — just confirm the transitive dependency is still maintained.
Weaver
How can I help you explore Laravel packages today?