Unique Violation Detector Laravel Package

Product Decisions This Supports

• Idempotency and duplicate-handling policy. Decides whether a repeat write is a 409 to the user, a silent success (idempotent create), or an upsert. Making that branch reliable is what this package does — it turns "was this a unique violation?" into a boolean instead of a guess.
• Check-then-insert vs. constraint-then-catch. The racy pattern (SELECT then INSERT) fails under concurrency; the correct pattern is to let the database enforce uniqueness and catch the violation. Adopting this package is the enabling decision to move to the correct pattern without driver-specific code.
• Retry and failure semantics for queues and APIs. A unique violation is a permanent failure and must not be retried; a deadlock or lock timeout must be. Conflating them inflates queue churn and produces duplicate side effects (double emails, double charges). This is a reliability decision, not a syntax one.
• Cross-driver commitment. If tests run on SQLite and production on MySQL or Postgres, any hand-rolled detection logic will diverge. This package normalizes SQLSTATE 23000 + driver codes (1062 MySQL, 23505 Postgres, 19 SQLite, 2601/2627 SQL Server) behind one check.
• Error-message and UX quality. Enables mapping a database error to a field-level message ("that email is already registered") instead of a generic 500, and supports attributing the violation to a specific constraint/index name on tables with multiple unique keys.
• Build vs. buy vs. use the framework. The real decision is a three-way: adopt this dependency, vendor ~50 lines of driver-code mapping into your own exception handler, or use Laravel's native UniqueConstraintViolationException (10.43+). This package only wins if you are outside that last case.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP versions that predate native unique-constraint exception classes, or you are on plain PDO without a framework abstraction.
• Multi-driver support is genuinely real — SQLite in CI, MySQL/Postgres in production, SQL Server somewhere — and string-matching 'Duplicate entry' is already spreading through the codebase.
• You need constraint-name extraction to attribute the failure to a specific column on a table with several unique indexes.
• You want to consolidate scattered str_contains($e->getMessage(), ...) hacks into one auditable place.

Look elsewhere when:

• You are on Laravel 10.43+ or 11: catch Illuminate\Database\UniqueConstraintViolationException natively and skip the dependency entirely.
• Doctrine DBAL or an ORM with portable exception conversion is already in the stack.
• Your dependency policy gates on adoption signals. Two stars, zero dependents, and a single maintainer is an audit and bus-factor liability for a long-support enterprise release — though the surface area here is small enough that "vendor the logic" is a credible third option.
• The need is one-off. Copy the driver-code map into your exception handler once and own it; you will not miss upstream.

How to Pitch It (Stakeholders)

To executives: This is a small MIT-licensed utility, not a feature. It converts ambiguous database errors into a dependable signal, which lets us stop double-writing records under concurrency and show users a sensible message instead of a 500. The cost is one dependency; the risk is maintenance — minimal adoption, single maintainer. Because the code is tiny, we can neutralize that risk by vendoring the logic or by using the framework's built-in equivalent where our Laravel version allows.

To engineering: It replaces string matching and per-driver error-code conditionals with a single check. It removes a class of check-then-insert race bugs, makes queue retry decisions correct (unique violation means fail, not retry), and behaves consistently across MySQL, Postgres, SQLite, and SQL Server. Read the source before adopting — it is small enough to audit in an afternoon and to fork if upstream goes quiet. Recommended framing: adopt the pattern first, and treat the package as one implementation of it.