Acorn Explained: How Laravel Features Work Inside WordPress

Emnes April 17, 2026

Venn diagram showing Acorn as the bridge between Laravel and WordPress

The single line in the Roots.io ecosystem that surprises most new users is this one: Acorn lets you run a Laravel application inside WordPress. Not “Acorn is Laravel-inspired.” Not “Acorn borrows patterns from Laravel.” Acorn literally boots a Laravel application — service container, configuration system, Blade rendering, Eloquent ORM, Artisan-style console commands, queues, mail, events, cache — on the same PHP request where WordPress is already running.

For Laravel developers coming to WordPress, this is transformative. You get the developer ergonomics of a modern PHP framework without giving up WordPress’s plugin ecosystem, admin UI, or content model. For WordPress developers curious about Laravel, Acorn is the least-disruptive on-ramp to Laravel features you’d otherwise need a full framework to access.

This post is a deep explanation of what Acorn actually is, how it works under the hood, and why Sage and Radicle depend on it. If you’ve used Sage 11, you’ve used Acorn already — it’s the engine that makes Blade work. If you want to understand what your theme is really doing, this guide is the foundation.

What Acorn Is, Technically

Acorn is a Composer package (roots/acorn) that loads a Laravel application inside a WordPress request. The current version as of April 2026 is Acorn 6.0.0, released March 2025, which supports Laravel v13 and requires PHP 8.3.

When you install Acorn — either as a Sage theme dependency or directly in a Bedrock project — three things happen on every WordPress request:

WordPress loads normally. Core files, must-use plugins, active plugins, the active theme — everything WordPress usually does.
Acorn bootstraps a Laravel application in-process. It reads config/ files, registers service providers, and initializes the Laravel service container.
Both frameworks run side by side. WordPress hooks fire as usual; Laravel features (Blade, Eloquent, service container) are available to anything that wants them.

Critically, Acorn doesn’t replace WordPress. It doesn’t intercept the WordPress bootstrap. Think of it as a Laravel application that quietly subscribes to WordPress’s request lifecycle and offers its services to whoever wants them.

Why Acorn Exists

WordPress the application is good. WordPress the developer framework is… incomplete. It has:

A hook system, which is powerful but unstructured.
A global state model ($wp_query, $post, get_option) that makes dependency injection hard.
PHP templates with inline logic, which don’t scale to complex designs.
Minimal primitives for background jobs, schema migrations, console commands, or dependency injection.
A REST API that’s reasonable for simple things and painful for complex ones.

Laravel has all of the above, refined over a decade. But porting WordPress functionality to Laravel means losing the plugin ecosystem and content model. Porting Laravel features to WordPress means reinventing them badly.

Acorn splits the difference. Keep WordPress for what it’s good at (content, admin UI, plugin ecosystem). Use Laravel for what it’s good at (dependency injection, modern templating, migrations, queues). They coexist on the same request.

What Acorn Actually Gives You

Acorn pulls in roughly 26 Laravel packages by default:

Blade Templating

The templating engine that powers Sage’s theme files. Template inheritance, components, slots, directives, compiled caching — all working the same way they work in Laravel.

Service Container

Bind interfaces to implementations, auto-resolve dependencies. Instead of new PaymentGateway() everywhere, type-hint PaymentGatewayInterface in your constructor and Acorn’s container handles the resolution.

Service Providers

Structured places to register container bindings, event listeners, view composers, and other framework-level wiring. Your theme’s app/Providers/ThemeServiceProvider.php is where you set up everything.

Eloquent ORM

Query the WordPress database with Laravel’s expressive ORM:

use Roots\Acorn\Models\Post;

$recent = Post::published()
    ->where('post_type', 'post')
    ->orderBy('post_date', 'desc')
    ->limit(5)
    ->get();

Far more readable than WP_Query for anything beyond trivial queries.

Configuration System

Laravel-style config/*.php files with dotenv support. config/app.php, config/database.php, and your own files live alongside WordPress’s native config and are loaded at bootstrap.

Console Commands

wp acorn is WP-CLI’s bridge to Acorn’s console. Commands live in app/Console/Commands/ and work like Laravel’s Artisan commands:

wp acorn make:block YourBlock
wp acorn view:cache
wp acorn your:custom-command --option=value

Validation

Laravel’s validation rules ported. Validate form submissions, REST API payloads, or any other input with declarative rule syntax.

Events and Listeners

Laravel’s event system, usable alongside WordPress hooks. Events are typed classes; listeners are structured handlers; both benefit from dependency injection.

Queues

Laravel’s queue system, configured with a driver (database, Redis, SQS). Push jobs to the queue and a worker process runs them asynchronously — real background jobs, not faked with wp_schedule_single_event.

Mail

Laravel’s mailer, with driver support for SMTP, Mailgun, SES, and more. Optional Acorn Mail package adds Blade-templated email composition.

Cache

Laravel’s multi-driver cache system (memory, file, Redis, Memcached) — a cleaner interface than WordPress transients for application-level caching.

How Sage Uses Acorn

Sage 11 ships with Acorn as a dependency and uses it for:

Blade rendering — every .blade.php file in resources/views/ is rendered by Acorn’s Blade engine.
View composers — app/View/Composers/ holds classes that attach data to specific views.
Service providers — app/Providers/ThemeServiceProvider.php registers theme-level bindings and hooks.
Theme.json generation — roots/acorn-theme-json package generates theme.json from your Tailwind config.
Block scaffolding — wp acorn make:block uses Acorn’s console system.

Every interaction with a Sage theme template goes through Acorn. You just don’t see it unless something breaks.

Acorn’s Place in Radicle

Radicle takes Acorn out of the theme and promotes it to the project root. Instead of Acorn being something Sage uses internally, it becomes the application framework for your whole WordPress project.

The Radicle directory structure reflects this — app/, config/, resources/, storage/ at the top level, not inside a theme. Your custom code is a first-class Laravel-style application; the theme is almost incidental.

This is overkill for simple sites but transformative for complex ones. A WordPress site with custom business logic — subscription billing, integrations with external services, complex user workflows — feels much more manageable when that logic lives in a Laravel-style application rather than scattered across theme functions and mu-plugins.

The Acorn Ecosystem: First-Party Packages

Beyond the core framework, Roots has released several first-party Acorn packages that add common WordPress functionality in a Laravel-native way:

Acorn Post Types (June 2025)

Declarative custom post types and taxonomies via config/post-types.php. A single config file replaces dozens of register_post_type() calls. Wraps the Extended CPTs library for reasonable defaults. Covered in detail in post 17 of this series.

Acorn User Roles (March 2026)

Declarative user roles and capabilities in config/user-roles.php. Solves the long-standing WordPress problem of capabilities added by deactivated plugins persisting in the database. Strict mode with explicit-denial capabilities makes role management a config artifact instead of a stateful mess.

Acorn AI (February 2026)

Bridges WordPress’s new Abilities API with Laravel’s laravel/ai package. AI features become service-container-resolved with dependency injection, API keys live in .env (not in wp_options), and AI-backed content works alongside the rest of your application.

Acorn Mail

Blade-templated email composition. Write emails as Blade views, benefit from component reuse and theme consistency between emails and web.

Acorn Prettify

A collection of small tweaks that remove WordPress’s default clutter — emoji scripts, jQuery Migrate, default feeds, etc. Ships with Radicle by default.

Blade Icons

Icon handling in Blade templates. <x-icon name="heroicons.arrow-right" /> renders any icon from any configured icon set.

Acorn Performance: Is It Slow?

Reasonable question. Loading a whole Laravel application on every WordPress request sounds expensive. In practice, it isn’t:

Acorn uses the same class-autoloading Composer does. Only files you actually reference are loaded.
The Laravel bootstrap is lazy. Acorn initializes the container but doesn’t construct services until something asks for them.
Blade templates compile once and cache the compiled PHP. Subsequent renders execute a standard require.
OPcache handles the compiled bytecode. There’s almost no redundant parsing.

Realistic overhead per request: 1–3 milliseconds, dominated by the one-time bootstrap. On a typical WordPress page that already takes 50–200 ms, it’s not measurable without profiling tools.

When to Use Acorn Beyond What Sage Gives You

Most Sage users interact with Acorn through Blade and occasionally a view composer. The deeper features (Eloquent, queues, service container, migrations) are there when you need them — and knowing when to reach for them is the skill:

Use Eloquent when a query is complex enough that WP_Query becomes an unreadable mess of meta_query arrays.
Use the service container when you have classes that depend on other classes and testing or refactoring would benefit from dependency injection.
Use queues when you have work that takes longer than a request — image processing, bulk email, external API calls with rate limits.
Use migrations when you need versioned database schema changes — custom tables, schema evolution across deploys.
Use validation for complex form handling, especially REST API endpoints.
Use events when the hook-system becomes hard to reason about and structured events would clarify intent.

You don’t need to use all of this on day one. Start with Blade, add features as genuine needs arise.

Frequently Asked Questions

Do I need to know Laravel to use Acorn?

Not really. If you’re just using Sage as a theme, you’ll touch Acorn through Blade and view composers — both are well-documented and approachable. The deeper features (service container, Eloquent) benefit from Laravel familiarity but aren’t required for basic theme work.

Does Acorn conflict with other WordPress plugins?

Rarely. Acorn coexists with WordPress peacefully; it doesn’t hook into anything WordPress doesn’t expect. Conflicts happen occasionally with plugins that also vendor Laravel packages with incompatible versions — solved by scoping dependencies via PHP-Scoper or by updating the plugin.

Can I use Acorn without Sage?

Yes. Add roots/acorn as a Composer dependency in a Bedrock project, register its service provider, and you can use any Acorn feature. Radicle is the most mature “Acorn without Sage” setup, but plain Bedrock + Acorn works too.

What Laravel version does Acorn support?

Acorn v6 supports Laravel v13. Older Acorn versions bridged earlier Laravel releases. The mapping isn’t always 1:1 — Acorn may lag Laravel by a point release while it catches up.

Can I use all Laravel packages in Acorn?

Most. Packages that assume a full Laravel application with a specific directory layout sometimes need small adjustments. The common Laravel packages (Socialite, Horizon, Telescope, Livewire) work with varying degrees of configuration.

How stable is Acorn for production?

Very. Acorn has powered Sage 10 and 11 on thousands of production sites since 2020. The v5 and v6 releases were substantial but backwards-compatible for most use cases.

The Framework You Didn’t Know You Were Using

If you’ve built a Sage theme, you’ve built on top of Acorn — even if you never wrote the word “Acorn” in your code. Every .blade.php file, every view composer, every wp acorn command runs through it.

For most developers, that’s all Acorn needs to be: a silent engine that makes Sage possible. For developers building complex WordPress applications — custom workflows, integrations, business logic — Acorn’s deeper features (Eloquent, migrations, queues, service container) let you write clean, maintainable code without giving up WordPress’s content model and plugin ecosystem. It’s the best of both frameworks on the same request.

At Emnes, we use Acorn via Sage on every theme we ship. For more complex client projects, we reach into the deeper Acorn features — service providers, Eloquent for reporting dashboards, custom console commands for data operations. The gradient from “theme framework” to “full application framework” is smooth.