Acorn Models Laravel Package

Product Decisions This Supports

• Build vs. buy for the data-access layer. If the product runs on Roots/Sage + Acorn, this package replaces an internal "Eloquent bridge to wp_posts / wp_postmeta / wp_terms" that would otherwise cost a sprint or more to write and maintain. MIT license, Composer-installable, no vendor lock-in — the cheapest way to answer "should we build our own abstraction?" is usually "no, fork this one."
• Content architecture: WordPress as system of record, Eloquent as query layer. Committing to this package is a decision to keep content in WP core tables and expose it through Laravel-style models, rather than migrating content to a custom schema or a headless CMS. That shapes roadmap options for years, so make it deliberately.
• Feature scoping for query-heavy surfaces. Faceted directories, filtered listings, sorted/paginated archives, and cross-entity views (posts + meta + taxonomies + authors) are where the package earns its keep: relationships, scopes, and eager loading instead of nested WP_Query loops and get_post_meta calls in templates.
• Roadmap sequencing for an API/headless layer. If a JSON API or front-end app is on the roadmap, this package is the shortest path to well-shaped, serializable content objects in a Laravel-fluent codebase — it de-risks the first increment of that work.
• Hiring and onboarding economics. A team of Laravel developers can be productive on WordPress content without learning WP_Query idioms first. That is a real, quantifiable reduction in ramp time and a factor in staffing decisions.
• Explicit non-goals to record. Not a solution for write-heavy editorial flows, not a replacement for plugins that hook WP_Query/the_content, and not a performance strategy. Documenting these prevents the package from being over-sold internally.

When to Consider This Package

Adopt when all of the following hold:

• The stack is already Roots/Sage on Acorn (v2+), PHP 8+, Composer-managed WordPress — this is a hard prerequisite, not a nice-to-have.
• The team is fluent in Eloquent and would rather read Post::with('meta')->where(...) than WP_Query args arrays.
• The dominant workload is read-heavy: archives, listings, filters, search result shaping, exports, reporting.
• You accept vendor risk as a known line item. With ~36 stars, zero dependents, and effectively a single maintainer, treat this as fork-and-own: pin the version, vendor the source, and budget a small amount of ongoing maintenance rather than assuming upstream responsiveness.
• You can live with WordPress' schema as-is — the EAV postmeta table and posts-table polymorphism (revisions, autosaves, attachments, nav items) require disciplined scoping and default filters.

Look elsewhere when any of these apply:

• Not on Acorn. Use WP_Query, wpdb, Timber, or WPGraphQL. There is no value here outside the Roots ecosystem.
• Heavy plugin surface. WooCommerce, page builders, SEO plugins, and multilingual plugins depend on WP_Query filters and global state. Eloquent bypasses those hooks; you will get subtly wrong content and hard-to-trace bugs.
• Write-heavy workflows. Writing posts/users through Eloquent sidesteps revisions, cache invalidation, and action hooks. This is an integrity risk, not an inconvenience.
• Hard performance or support requirements. No object-cache awareness, no commercial backing, no SLA. For high-traffic sites with caching tiers, validate query counts before committing.
• Multisite or non-standard table prefixes without an owner willing to verify configuration and test it.
• You need community validation. Zero dependents is a signal. If your organization requires a "used by others" bar for dependencies, this does not clear it.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed accelerator for one specific stack — WordPress sites built on the Roots/Sage + Acorn framework. It lets our Laravel-fluent developers build content-driven features faster by querying WordPress data with the same patterns they already use, avoiding a custom bridge we would otherwise have to write and maintain ourselves. The cost is negligible; the risk is vendor concentration (a small open-source project with a single maintainer), which we contain by forking the source, pinning the version, and budgeting a few days a year of internal upkeep. It is not a strategic dependency and it is not reversible-costly — if it stalls, we swap to WP_Query or a GraphQL layer behind our own interface.

To engineering: Thin mapping of WordPress core tables to Eloquent models — models, relationships, scopes, eager loading. Use it as a read/query layer for archives, listings, filters, and API payload shaping. Do not use it as a write layer for posts or users unless we explicitly re-implement the WordPress hooks and cache invalidation we'd be bypassing. Assume we own the fork: expect to patch it, pin it, and keep an integration test around the models we rely on. If a feature depends on plugin behavior or WP_Query filters, that feature stays on WP_Query.