Doctrine Psql Enum Laravel Package

Product Decisions This Supports

• Schema design: DB-enforced enums vs. application-only validation. This package makes PostgreSQL custom enum types a practical option for Laravel/PHP teams, so the decision "do we trust $table->string('status') + validation, or do we enforce the value set in the database?" becomes a real architectural choice rather than a default. Directly relevant to status/state columns: order lifecycle, payment state, subscription tier, fulfillment stage, KYC/onboarding steps.
• Build vs. buy for the Doctrine type layer. The alternative is writing and maintaining your own Doctrine\DBAL\Types\Type subclass plus conversion/SQL-declaration logic. This package collapses that to a config line — a low-cost procurement decision, not a platform bet.
• Roadmap: PHP native enums as the single source of truth. If we standardize on PHP 8.1 enums as the domain modeling primitive for closed value sets, this package lets one definition drive the PHP type, the database column, and (via casts/serializers) the API contract. That removes a class of "enum drift" bugs where the DB and app disagree.
• Migration and release-process decisions. Native PG enums change how we version schema: ALTER TYPE ... ADD VALUE has transactional and ordering constraints, and value removal requires a type rewrite. Adopting this forces us to decide how enum evolution is governed — a process question the PM owns as much as engineering.
• Data/reporting use cases. Typed, constrained columns simplify BI, warehouse syncs, and audit queries ("count of orders stuck in pending_review") because invalid states cannot exist in the table.
• Explicitly not a decision driver: it is not an ORM strategy. Laravel's Eloquent stays as-is; this only matters at the DBAL/schema boundary (migrations, column changes), which is where Laravel already pulls in doctrine/dbal.

When to Consider This Package

Adopt when:

• The stack is PostgreSQL + PHP 8.1+ and Doctrine DBAL is already present (Laravel includes it for column-altering migrations; a Doctrine-based service has it natively).
• The value set is small, stable, and truly closed (≤ ~20 values, changed a few times a year).
• You want database-level integrity for a domain where bad states are expensive — payments, entitlements, compliance status, medical/regulated workflows.
• You are willing to vendor or pin the dependency: 25 stars, zero dependents, and a single maintainer mean we own the failure mode. Budget time for a read-through of the type implementation and a fork contingency.
• You have a narrow, bounded domain to pilot in, so a retreat to varchar + check constraint is cheap.

Look elsewhere when:

• The app is pure Eloquent with string columns and Laravel's built-in enum cast — that already covers most CRUD needs with zero new dependencies.
• Any non-PostgreSQL target (MySQL/SQLite) or a multi-database product surface.
• The value set is volatile or tenant-extensible (per-customer statuses, configurable pipelines). Enums are rigid by design; use a lookup table with a foreign key instead.
• Enum values must be reordered, renamed, or removed routinely — native PG enums make this a migration project.
• Your dependency policy requires broad adoption, active CVE response, or SOC2-style vendor assurance. This does not clear that bar today.
• You need per-row metadata attached to the value (labels, translations, flags) — a reference table wins.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, MIT-licensed integration library that lets our PHP code and our PostgreSQL database share one authoritative definition of closed value sets like order status or payment state. The business value is data integrity: invalid states become impossible to write rather than merely rejected by application code, which reduces a recurring class of bugs and clean-up work in reporting and audits. Cost is low — a thin adapter, roughly a day or two of engineering — and the license carries no commercial obligation. The main risk is not technical but organizational: the project is early-stage with a single maintainer and almost no downstream adoption, so we should pilot it in one bounded domain, pin the version, and keep a trivial fallback to a constrained string column. Recommendation: approve a scoped spike, not a platform-wide standard.

For engineering (the practical case): It provides a Doctrine DBAL custom type mapping PHP 8.1 backed enums to PostgreSQL CREATE TYPE ... AS ENUM, so enum values live in one place and schema comparisons work. Integration is configuration, not code. The tradeoffs to accept up front: ALTER TYPE ... ADD VALUE cannot be rolled back inside a transaction and older PG versions restrict its use in some migration contexts, so enum evolution needs its own migration playbook; the type is not removable without a full rewrite; and Doctrine DBAL must be a first-class dependency rather than an incidental one. Before adoption we want a code review of the type implementation, a pinned version, and a documented exit path (revert to varchar + CHECK constraint) so the pilot cannot become a lock-in.