Eloquent Binary Uuid Laravel Package

Product Decisions This Supports

• Build vs buy for binary UUID storage: the package is now mature enough that its remaining releases are about diagnostics rather than capability. This release adds no new features — it makes existing failures legible. That shifts the calculus toward "buy" (adopt) for teams considering hand-rolling binary UUID columns for MySQL index performance.
• Data-integrity posture: the one behavioural change is a safety improvement — values the creating hook cannot encode (neither a UUID string nor 16 raw bytes) now throw instead of being written and silently truncated by MySQL when strict mode is off. Supports decisions where silent corruption is an unacceptable failure mode.
• Onboarding cost and support load: error messages now name the model, the column, and the setting to fix ($uuidColumn / binary-uuid.default_column), plus a new README Troubleshooting section. This directly reduces the time a new engineer spends debugging a misconfigured UUID column — a recurring cost in any project using the package.
• Roadmap signal: a release scoped entirely to error clarity and a latent TypeError fix indicates a maintenance-minded package. Relevant if you are deciding whether to commit to it as a long-term dependency versus an unmaintained alternative.
• Use cases it serves: models keyed by BINARY(16) UUIDs, foreign key columns built via foreignUuid(), throughput- or storage-sensitive tables where a 36-byte CHAR key is too expensive, and teams that want automatic ID assignment without writing observers.

When to Consider This Package

Adopt when:

• You want UUID primary keys stored as BINARY(16) rather than CHAR(36) for storage and index efficiency on MySQL.
• Your team is comfortable with an opaque binary column that is not human-readable in raw SQL dumps or BI tools, and has tooling or casts to render it as a string at the edges.
• You are standardising several models on binary UUIDs and want one convention ($uuidColumn, binary-uuid.default_column) instead of per-model glue.
• You value failure being loud: v1.11.0 now refuses to write values it cannot encode, which surfaces misconfiguration at insert time rather than as corrupted rows discovered later.
• Your models already store UUIDs in binary form. Correctly configured models behave exactly as before this release.

Look elsewhere when:

• You need portable UUID storage across Postgres, SQLite and MySQL with identical behaviour — native uuid column types or a string-UUID package are simpler.
• Your team depends on reading primary keys directly from the database, logs, or exports; binary columns are a real operational tax.
• You require human-sortable or time-ordered identifiers (UUIDv7, ULID) — this package's scope is the binary column mechanics, not identifier strategy.
• You are mid-migration and have historical rows holding malformed values: v1.11.0 will now throw on those inserts rather than letting them through, so you need to clean data or handle the exception deliberately before upgrading.

How to Pitch It (Stakeholders)

Executives: this is a small, low-risk maintenance upgrade to an internal dependency with no API changes. The substance is error quality and one safety guardrail: previously, a misconfigured UUID column could accept a bad value and let MySQL truncate it silently — a data-integrity failure that tends to surface months later during reconciliation. That path now fails immediately with a message naming the model and column. Net effect is lower incident risk and lower support burden, at effectively zero migration cost for correctly configured models.

Engineering: v1.11.0 replaces opaque ramsey/uuid failures ($bytes string should contain 16 characters.) with a package-owned InvalidBinaryUuidException thrown from uuid() and foreignUuid(), naming the model, the column, the observed byte length, and the specific setting to change. UUIDs stored in string form are called out as a distinct, more actionable case. The creating hook now rejects values it cannot encode instead of passing them through — the only behavioural change, and it only affects inserts that were already storing wrong data. Also fixes a latent TypeError where non-string values reached Uuid::isValid(). Upgrade is a drop-in; audit any code path that assigns non-UUID values to the UUID attribute before deploying.