Eloquent Binary Uuid Laravel Package

Getting Started

• Install the package and publish its config so binary-uuid.default_column is available. That config value is the column the package looks for when a model does not declare one.
• Add the package trait to a model, make sure the UUID column is a 16-byte binary column (not char(36)), and let the creating hook generate the value. If the column is not the default (id), set $uuidColumn on the model.
• First use case: a model with a binary UUID primary key. Create a record, then read the UUID back in string form at the application edge (API resource, route key) while keeping the raw 16 bytes in the database.
• When something looks wrong, check the README Troubleshooting section first — as of v1.11.0 the runtime error messages are written to be searchable and to point at the exact model, column and setting to fix.

Implementation Patterns

• Trait + explicit column. Declare $uuidColumn on every model whose UUID column is not id. Rely on binary-uuid.default_column only for a single app-wide convention; per-model declarations are clearer and produce better error messages when misconfigured.
• Binary in the database, string at the edges. Keep binary(16) storage for index size and join performance, and convert to the canonical string form in accessors, API resources and getRouteKey(). Do not store the string form in the binary column — the package now calls that case out explicitly.
• Foreign keys. Use the package's foreignUuid() helper so FK columns match the referenced binary(16) type. A char(36) FK against a binary(16) PK will not join, and the failure is silent.
• Migrations. Use the package's column helpers for both primary and foreign UUID columns so the type is consistent across the schema; add indexes on binary columns as usual.
• Factories and seeders. Do not assign UUIDs manually. Omit the column and let the creating hook fill it; assign only when you deliberately need a fixed UUID, and then assign the string form.
• Integration tip. Because keys are binary, keep a single conversion boundary (a base model, trait method or API resource) rather than scattering bin2hex/Uuid::fromString calls. This is also the place to handle the string representation for logs and URLs.

Gotchas and Tips

• New exception in v1.11.0. Verbanent\Uuid\Exceptions\InvalidBinaryUuidException is thrown from uuid() and foreignUuid() when the column does not hold a 16-byte binary UUID. The message names the model, the column and the byte length found, and tells you to point $uuidColumn or binary-uuid.default_column at the right column. This replaces the opaque ramsey/uuid message ($bytes string should contain 16 characters.) — treat the new message as the diagnosis, not a symptom.
• String-form UUIDs are reported separately. If the column contains a UUID in string form, the package flags it as "written without the package" — usually raw SQL, a database importer or a legacy writer. Find that writer and backfill; do not paper over it with a cast.
• One behavioural change. The creating hook now rejects values it cannot encode (anything that is neither a UUID string nor 16 raw bytes) instead of passing them through. Previously MySQL outside strict mode would truncate these silently. Correctly configured models are unaffected; inserts that were already storing wrong data will now throw. Check importers and any code that sets the UUID column by hand.
• Non-string assignment fixed. $model->uuid = 3 previously produced a TypeError inside ramsey/uuid because Uuid::isValid() is typed string; it now reports the real problem. If you catch exceptions around model saves, widen the catch to the package exceptions.
• AccessedUnsetUuidPropertyException now names the column and model too, which makes it useful for tracking down which accessor ran before the UUID was populated.
• Debugging binary columns. SQL clients show binary(16) keys as mojibake or hex. Use BIN_TO_UUID() / UNHEX() in ad-hoc queries, or convert via the package's string accessor, rather than copying raw bytes around.
• Enable MySQL strict mode. The silent-truncation failure mode this release closes only existed because non-strict mode accepted short values; strict mode surfaces schema/type drift earlier.
• Extension points. Override $uuidColumn per model, set binary-uuid.default_column for the app default, and use the exception types (InvalidBinaryUuidException, AccessedUnsetUuidPropertyException) for targeted handling in tests or data-repair commands.