Acorn Db Laravel Package

Product Decisions This Supports

• Build vs. buy for the data-access layer. This package answers a recurring question on every Acorn/Sage build: do we write our own repository layer wrapping WP_Query, or standardize on Eloquent models over WordPress core tables? Adopting it is a real architecture decision — it defines the contract every feature touches — so it belongs in a technical spike, not a sprint ticket.
• Roadmap: headless / decoupled WordPress. If the roadmap includes serving content to a JS front end, a mobile app, or a Laravel service, Eloquent models give you a serializable, testable domain layer instead of ad-hoc WP_Query arrays. This is the strongest strategic justification for the dependency.
• Feature scoping: read-heavy vs. write-heavy surfaces. Reading posts, terms, users, and comments through models is low-risk and high-DX payoff. Anything that writes — publishing, status transitions, meta updates — is where WordPress's hook system (save_post, cache invalidation, plugin side effects) stops being automatic. Scope features accordingly before committing.
• Effort estimation and staffing. Laravel-fluent engineers become productive on WordPress content faster when the data layer looks like Laravel. This directly affects how you estimate onboarding cost and how you write job reqs for hybrid WP/Laravel roles.
• Consolidation away from WP_Query sprawl. Legacy Sage themes tend to accumulate query logic across templates. Standardizing on models is a credible migration target and gives you a measurable refactor epic.
• Vendor and exit strategy. With 36 stars and zero dependents, adopting this is closer to adopting an internal library with a public changelog. That's a decision about whether you're willing to own it, not just consume it.

When to Consider This Package

Adopt when all of the following hold:

• The project is already on Acorn + Sage (or a Roots-based stack). Outside that, there is no reason to look at this — it is not a general-purpose WordPress ORM.
• Content access is predominantly read-oriented, or your write paths already go through WordPress APIs and you only use models for reads.
• Your content model is mostly core tables — posts, postmeta, terms, term relationships, users, usermeta, comments. Custom post types are usually fine; custom tables (WooCommerce, ACF's options tables, most commerce/membership plugins) are not covered out of the box and will need extending.
• You have an engineer who can read the source in an afternoon and patch it. Assume you will need to.

Look elsewhere — or stay on WP_Query — when:

• Writes must trigger WordPress behavior. Saving through Eloquent bypasses wp_insert_post/wp_update_post, which means hooks, revisions, autosaves, notifications, and third-party plugin listeners may not fire. If your product depends on those, either keep writes in WordPress APIs or budget for carefully re-firing hooks.
• Performance is tight on large datasets. EAV meta tables plus Eloquent's hydration cost plus a likely-missing integration with the WordPress object cache means N+1 queries and cold caches are a live risk. Direct SQL or cached WP_Query may simply be faster, and you should measure before you standardize.
• You want a supported, widely-adopted dependency. Corcel is the more established option for Eloquent-on-WordPress and has a much larger community. If support and ecosystem matter more than tight Acorn integration, that's the comparison to run.
• Your team is Timber/Twig-oriented rather than Blade/Eloquent-oriented, or you're not prepared to own a low-bus-factor fork.

How to Pitch It (Stakeholders)

Executive summary. This is a small open-source adapter that lets our Laravel-style WordPress stack (Acorn/Sage) talk to WordPress content using Laravel's standard database models instead of WordPress's native query functions. It is a developer-experience play, not a customer-facing feature: it shortens time-to-market on decoupled/headless builds and makes Laravel engineers productive on WordPress faster. The trade-off is real — the package has a small maintainer base and no meaningful downstream adoption, so we should treat it as code we may have to own rather than a vendor we can lean on. Recommendation: adopt for read-side content access in a time-boxed spike, keep writes on WordPress's native APIs, and make a keep/fork/replace call once we've validated it against our actual content model.

For engineering. You get first-class models for posts, meta, terms, users, and comments, with relationships — a natural fit for Blade views, API resources, and tests where WP_Query arrays are painful. You inherit risk: writes bypass WordPress hooks and cache invalidation, meta is EAV and prone to N+1, and custom/plugin tables need hand-rolled models. Pin the version, read the source, wrap it behind our own repository interfaces so it stays swappable, and benchmark against WP_Query on representative data before we commit.