Eloquent Driver Laravel Package

Product Decisions This Supports

• Content storage architecture: flat-file vs. database-backed. This package is the concrete lever for a decision most teams defer because it feels like a re-platforming bet. Statamic normally stores content as Markdown files; the Eloquent driver swaps persistence for relational tables — and it does so per repository (entries, terms, globals, navigations, assets, users, revisions). A PM can therefore scope adoption to "entries only," validate against real traffic, and stage the rest later. That reframes the decision from a one-way architecture bet into a configurable, reversible increment — the single most useful property here for planning purposes.
• Scaling roadmap and performance investment. Flat files serialize poorly against large content volumes, complex queries, and editorial concurrency. Database-backed content unlocks indexing, cursor pagination, aggregates, and cheap joins. The v5.12.3 fixes — reading entry order from the order column, faster hydration of dated entries with a custom entry class, corrected timezone handling on save — map directly to page-render latency, listing reliability, and publish-time accuracy. Those are the metrics to cite when justifying the work: they are user-visible quality signals, not internal plumbing.
• Build vs. buy. The alternatives are commissioning a bespoke DB-backed content layer or migrating off the CMS entirely. This is a maintained MIT-licensed adapter that preserves the editorial UX, blueprints, template tags, and Control Panel while changing only the persistence layer — substantially cheaper than a rebuild. The diligence caveat is real and should be stated plainly: 129 stars and zero tracked dependents means thin third-party validation. That is a support-cost input, not a disqualifier.
• Data governance, compliance, and auditability. The timezone-shift-on-save fix is a governance issue, not cosmetic. Publish dates, scheduled releases, and timestamped audit trails must be correct. If content timestamps feed reporting, legal retention, or regulatory disclosure, applying this patch is a correctness requirement — and any rows written on earlier 5.12.x should be audited.
• Integration and data-product surface. Once content lives in SQL, product, CRM, and analytics data can be joined to it directly without an ETL step off a filesystem. This is the enabler for personalization, editorial reporting, and content-performance dashboards — roadmap items that are awkward or expensive against flat files. Sequence these after the storage migration proves stable; they are the payoff, not the justification.
• Operational model and release process. Moving content into the database changes how you ship. Content stops being git-versioned and becomes part of the migration, backup, and environment-seeding story. That is a PM-visible tradeoff — better transactional integrity and reuse of existing DB observability, weaker file-level diffability and repository-based content review — and it should be decided deliberately rather than discovered mid-sprint.
• Rollback and risk posture. Because drivers are configurable per repository, adoption is reversible: revert config, clear the stache, and you are back on files. This supports a phased release plan with a genuine safety net rather than a one-way door — valuable when negotiating timeline with stakeholders who have seen CMS migrations fail.

When to Consider This Package

Adopt when:

• You are already running Statamic on Laravel, and content volume, query complexity, or editorial concurrency is genuinely straining flat files. If you cannot name the threshold you are crossing — record count, render latency, concurrent editors — the case is weak.
• You need transactional integrity, relational joins, or want to point existing database backup, monitoring, and observability tooling at your content.
• You run multiple environments or instances where synchronizing content files is operationally painful or error-prone.
• You have high-volume, date-driven collections (news, events, releases) where ordering reliability and hydration performance are user-visible quality issues.
• You want to consolidate the CMS into the database platform your team already staffs, rather than adding another system to operate.
• You are prepared for a phased rollout — entries first, assets and globals left on disk — shipped and observed before further expansion.

Look elsewhere when:

• The site is small enough that flat-file simplicity, portability, and git-based editorial workflows outweigh query power. The migration cost will not pay back.
• Your team cannot own schema migrations and database operations for content tables. This package transfers operational responsibility to you; it does not remove it.
• You depend on file-level content versioning, content review in pull requests, or editing content directly in a repository. That capability is lost, not degraded.
• You are not committed to Statamic, or you need a CMS whose content model is database-native rather than adapted onto one.
• Your risk tolerance does not accommodate a small ecosystem footprint. Zero dependents is not disqualifying given the maintainer's track record, but it means you are an early adopter and should budget for self-support and your own test coverage.
• You depend on addons you have not inventoried. "Most addons are compatible" is not an inventory; verify each one before committing.

How to Pitch It (Stakeholders)

For executives: This is a mature, actively maintained extension that lets our existing CMS run on the relational database we already operate, instead of on flat files. It reduces operational overhead, improves performance as content grows, and makes content available for analytics and product integrations without a separate data pipeline. Critically, this is not a re-platforming: adoption is per-content-type and fully reversible by changing configuration, so we pilot on one content type and expand only if results justify it. The current release is a maintenance patch — three targeted fixes, no breaking changes, no new platform requirements — so there is no migration program or retraining cost attached. It specifically improves ordering reliability, render performance on date-driven listings, and timestamp accuracy, reducing the risk of content appearing out of sequence or with incorrect publish times. The one diligence caveat to state openly is ecosystem maturity: the package has a modest public footprint, so we should plan to own our testing and support rather than rely on community answers. Net: a low-risk, high-reversibility infrastructure improvement with a bounded pilot and a clear rollback.

For engineering: Treat this as an incrementally adoptable persistence change, not a migration event. Configure per repository in config/eloquent-driver.php; the recommended path is entries first, assets and globals left on file, shipped and observed before expanding. Keep Statamic's facades and template tags for rendering and augmentation; reach for Eloquent directly only where it wins — joins, aggregates, cursors, reporting screens. Extend the package's models rather than forking them so upgrades stay trivial. This release is a patch, safe to fold into the normal dependency cadence, but handle three things: it now reads entry order from the order column (backfill or re-import if listings sort oddly after upgrading), it speeds hydration of dated entries using a custom entry class (teams that subclass early and lag on patches will feel the prior cost), and it fixes a timezone shift on save (audit rows written on earlier 5.12.x before correcting them). Expect concrete workflow changes: content leaves version control, so migrate --force joins the deploy script, and we must decide deliberately whether content is seeded per environment, restored from production, or authored in place. RefreshDatabase plus factories now covers content fixtures — a net testing win. Watch three failure modes: clear the stache after any driver flip or import (stale cache, not missing data, explains most "lost content" reports); the users repository can lock you out of the Control Panel if an import lands badly, so migrate it last, in staging, with a one-line config rollback ready; and assets move only their metadata — files stay on disk. Keep the flat-file content directory in the repo for at least the first week in production; reverting config and clearing cache is a cheap, complete rollback.