Custom Index Bundle Laravel Package

Product Decisions This Supports

• Index strategy as a product decision, not just a DBA detail. Search, filtering, and "sort by relevance" features all live or die on index design. This bundle lets a team declare non-standard indexes (partial/conditional, expression/functional, full-text, and Postgres-specific types like GIN/GiST/BRIN) alongside the entity definition instead of hand-writing raw SQL in migrations — which turns "can we ship search this quarter?" into a tractable, low-cost roadmap item.
• Build vs. buy for search. The most common reason teams reach for Algolia/Elasticsearch/Meilisearch is a filtering or full-text requirement. Native database indexes (trigram, GIN on tsvector, partial indexes on status/tenant_id) cover a large share of these cases at zero marginal infrastructure cost. This package is the enabling tool for the "don't buy a search service yet" branch of that decision — usually a five-figure annual saving and one fewer system to operate.
• Scope-cut lever for the roadmap. When a feature is blocked on query performance (e.g., "active subscriptions by tenant, sorted by created_at"), the cheap answer is often a composite/partial index rather than a read-replica, a cache layer, or a denormalized table. Having a declarative way to add those indexes shortens the path from "slow feature" to "shipped feature."
• Schema ownership and environment parity. Declaring indexes in code rather than ad-hoc SQL makes index changes reviewable in PRs, reproducible across dev/staging/prod, and diffable against the entity model. That is a process decision (migration discipline, code review of DB changes) that PMs often end up arbitrating after an incident.
• Supply-chain and dependency risk — improved, not resolved. v1.1.0 (up from v1.0.3, Oct 2024) adds Doctrine ORM 3 compatibility plus CI, PHPStan, php-cs-fixer, and a Dockerized dev environment. That is a meaningful maintenance signal: the package is not abandoned, it now tracks the current major of the ORM it hooks into, and regressions are more likely to be caught before they reach us. It remains a small single-maintainer utility (27 stars, ~0 dependents, MIT) with no support contract, so the adoption posture is still "bounded trial with an exit plan," just with a lower-than-before chance of being stranded on an old ORM.

When to Consider This Package

Consider it when:

• The stack is Symfony + Doctrine ORM — this is an Intaro Symfony bundle, not a Laravel package. If you are on Laravel/Eloquent, this is not adoptable as-is; the equivalent is raw DB::statement() calls inside migrations, or a small in-house helper. v1.1.0 does not change this.
• You are on Doctrine ORM 3 (or planning the upgrade). Before v1.1.0 this was a blocker — the bundle's metadata/schema-tool integration had to be updated for ORM 3's reworked schema APIs, and now it is. If you are mid-migration to ORM 3, this release is the reason the bundle is back on the table rather than a reason to wait.
• The primary database is PostgreSQL (or another engine with advanced index types) and you actually need partial, expression, or full-text indexes — not just ordinary B-trees.
• You have a small team without a dedicated DBA, where "write the index in the entity metadata" is meaningfully safer than "remember to write the right SQL."
• You want index definitions to be reviewable and versioned in application code, and you're willing to accept the coupling that comes with that.
• You can treat it as a spike/trial: time-boxed evaluation, with the generated SQL captured in a test so you can migrate off it later. Pin to ^1.1 and check the raised doctrine/orm / PHP constraints against your platform before committing.

Look elsewhere when:

• You're on Laravel, Eloquent, or any non-Doctrine stack. Ecosystem mismatch is still disqualifying regardless of the release. The new CI does not create a Laravel integration.
• Your workload is standard B-tree indexing on MySQL — the framework's built-in index support already covers it, and the bundle adds a dependency for no gain.
• Your team is already migration-first with strong SQL review; hand-written indexes are simpler and remove a third-party dependency entirely.
• You need active maintenance, a support contract, or a security-response commitment. CI and static analysis are good engineering hygiene, not an SLA. Still one maintainer, still zero dependents — you remain the maintainer of last resort.
• You are pinned to Doctrine ORM 2 and cannot move, and the new floor constraints in v1.1.0 do not resolve for you — stay on v1.0.3 knowingly, or skip.
• You need indexes that change frequently at runtime, or you're considering this as a substitute for proper query/architecture work — an index is a bandage, not a design.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a recurring pattern where a feature ships and then needs a database index to be usable in production — today that means ad-hoc SQL, manual ops coordination, and occasional environment drift. This is a small, free, MIT-licensed library that lets engineers declare those indexes in code so they're reviewed, versioned, and deployed like any other change. The near-term value is shipping search and filtering features without buying an external search service, plus fewer production performance surprises. The project just shipped v1.1.0, which brings it current with Doctrine ORM 3 and adds automated tests and static analysis — a good sign it isn't abandoned. The risk is unchanged in kind: it's a low-traffic, single-maintainer project in the Symfony ecosystem with no support contract, so I still recommend a time-boxed trial on one feature rather than company-wide adoption — we keep the generated SQL under test, so backing out is cheap. Note this only applies to our Symfony/Doctrine services; it does nothing for our Laravel ones.

For engineering (summary): intaro/custom-index-bundle extends Doctrine metadata so non-standard indexes — partial, functional/expression, and Postgres-specific types — are declared on the entity and emitted through the normal schema tooling. v1.1.0 adds Doctrine ORM 3 compatibility (the significant change — the schema/metadata integration had to be reworked for ORM 3), PHPStan and php-cs-fixer cleanup, a Dockerized dev env, and CI, so the codebase now has automated regression coverage it previously lacked. Constraints to note: (1) it is Symfony/Doctrine, not Laravel — no fit for our Eloquent services, and the release doesn't change that; (2) it is a thin abstraction over CREATE INDEX, so treat the generated DDL as an artifact we own and assert on it in tests — this matters more now that the ORM-3 schema path has changed; (3) maturity is still low (27 stars, ~0 dependents, single maintainer) — no SLA, so pin ^1.1, vendor it if needed, and avoid making it load-bearing for anything we can't rewrite as plain SQL in a day. Recommended evaluation: one representative feature on ORM 3 (e.g., tenant-scoped partial index on an active-records table), diff the generated CREATE INDEX against what we'd write by hand, measure query plan and latency before/after, and decide within a sprint.