Acorn Models Laravel Package

Technical Evaluation

Architecture fit. tiny-pixel/acorn-models is a bridge between two data-access paradigms: WordPress's procedural $wpdb/WP_Query layer and Laravel's Eloquent ORM. It only makes architectural sense inside a Roots stack — Sage theme + Acorn (which boots Illuminate components into WordPress). If the target project is not already Acorn-based, this package is not a reason to adopt Acorn; it is a dependency you inherit after that decision is made. Treat it as an additive read layer, not a replacement for WordPress's query layer.

Integration feasibility. Composer-installable, MIT-licensed, and small in surface area — which is good for a spike and bad for confidence. Reading WordPress data (posts, postmeta, terms, users) through Eloquent is mechanically feasible because the schema is plain MySQL. Writing through Eloquent is where feasibility collapses: WordPress's correctness depends on hooks (save_post, clean_post_cache, transition_post_status), object-cache invalidation, and capability/sanitization paths that an Eloquent save() will not trigger.

Technical risk — high. Specific concerns:

• Abandonment / bus factor. 36 stars, 0 dependents, published by a small agency. There is no evidence of a user base large enough to surface regressions. Assume you may be the maintainer.
• Version drift. Acorn has moved through multiple major versions (and Laravel 9/10/11 underneath); a package at this adoption level is unlikely to track them promptly. Pin and test.
• EAV modeling. wp_postmeta/wp_usermeta are key-value with serialized payloads and no foreign keys. Eloquent relationships over them are convenient but generate pathological joins and are blind to PHP-serialized values.
• Dual-ORM anti-pattern. Mixing WP_Query and Eloquent in one request invites divergent results, duplicate queries, and cache-coherency bugs that are extremely hard to reproduce.
• Identifier mismatch. Package name (tiny-pixel/acorn-models) and repository (pixelcollective/acorn-db) differ — a supply-chain/traceability smell worth resolving before trusting the Composer source.

Key questions for the maintainer/vendor:

1. Which Acorn, Laravel, PHP, and WordPress versions are explicitly supported and CI-tested?
2. Is the intended contract read-only, or are writes supported with hook and cache parity?
3. Does it respect $table_prefix, multisite table routing, and WP's DB credentials from Acorn's connection config?
4. How are custom post types, custom taxonomies, and meta casts modeled?
5. Is there test coverage against a real WordPress schema, and what is the issue-response history?
6. Why does the repository name not match the published package name?

Verdict: viable as a low-blast-radius read layer in an existing Acorn project; not viable as a primary data-access strategy or anywhere writes are required.

Integration Approach

Stack fit. Requires PHP 8.x, Composer, roots/acorn, and illuminate/database. Natural home is a Sage 10/11 theme or an Acorn plugin, alongside existing Blade/Composer tooling. It composes cleanly with headless/REST or GraphQL surfaces where you want typed models instead of array-shaped WP_Query results.

Migration path. Do not refactor working WP_Query code. Introduce the package as a sidecar for net-new, read-only surfaces: admin reporting screens, internal dashboards, export jobs, or a headless API endpoint over a single custom post type. Keep WordPress-native queries on all user-facing and hook-sensitive paths.

Compatibility gates to clear before writing code:

• Confirm the exact Acorn major and its pinned Illuminate version against the package's constraint.
• Confirm the Eloquent connection resolves to WordPress's $wpdb credentials and honors $table_prefix.
• Confirm behavior under multisite if applicable (wp_2_posts routing is a common break).
• Confirm interaction with a persistent object cache (Redis/Memcached) — Eloquent bypasses it entirely.

Sequencing:

1. Spike (1 sprint). Branch install; verify boot, connection, prefix, and one read query against a staging clone.
2. Read model #1. One CPT plus its meta, exposed behind an internal-only route. Benchmark query count and memory against the equivalent WP_Query.
3. Parity tests. Assert Eloquent results equal WP_Query results for the same filters, including status, ordering, and taxonomy constraints.
4. Decision gate. Go/no-go on broader use based on performance and maintainer responsiveness.
5. Writes (only if unavoidable). Feature-flag, wrap in explicit hook calls (do_action('save_post', ...), clean_post_cache()), and add regression tests proving WP admin and REST see the same state.

Operational Impact

Maintenance. Highest ongoing cost of this decision. With 0 dependents and 36 stars, dependency upgrades will not be community-validated. Plan to pin the version, vendor/fork it into your monorepo, and assign a named owner. Budget roughly a few days per Acorn or Laravel major upgrade to re-validate.

Support. Community-only — GitHub issues and the Roots Discord/Discourse. No SLA, no security advisory process you can rely on. For a client-facing product this must be accepted explicitly as a risk, not assumed away.

Scaling. Eloquent hydration over large wp_posts tables is memory-hungry compared to WordPress's tuned WP_Query + object cache. Expect:

• N+1 queries from eager-loaded relations over meta tables.
• Unindexed EAV joins degrading on sites with heavy postmeta bloat.
• Duplicate query load when Eloquent and WP_Query both run in a request.

Mitigate with select() projections, chunking, explicit with() eager loading, and a hard rule that Eloquent is never used inside a hot page-render path.

Failure modes to instrument for:

• Stale object cache after any Eloquent write (silent, users see old content).
• Corrupted PHP-serialized meta written as plain strings.
• Schema assumptions broken by plugins that add columns or shadow tables.
• Acorn upgrade silently breaking model bootstrapping.
• Divergence between WP_Query and Eloquent results for the same logical filter.

Ramp-up. Requires dual competency — Laravel/Eloquent fluency and WordPress internals (hooks, caching, capabilities). Docs are sparse, so plan one to two sprints for a mid-level Laravel developer to become productive, including writing internal documentation and a "never do this" list. Without that, the package will be used in exactly the places it is most likely to break.