What is WP Emerge

by Atanas Angelov | Oct 27th, 2018 | Tutorials

WP Emerge is a developer-oriented WordPress framework that draws from experience with other PHP frameworks like Laravel, Symfony and Slim.
While the framework is theme-agnostic, there’s also a starter theme built specifically around it which reduces development friction and enhances WP Emerge’s tools.

A quick overview

The Framework:

  • Enables you to write testable, MVC-powered themes with a focus on custom functionality.
  • Allows registering and handling of custom URLs without having to deal with the clunky Rewrite API.
  • Has no magic implementation details to cause plugin or theme incompatibilities.
  • Does not force you to use a custom template engine like Blade or Twig, but supports them in case you wish to.
  • Does not limit you to a single template engine – you can use a mix which enables incremental integration into legacy projects, for example.
  • Works alongside the template hierarchy but allows you to override it when needed.
  • Provides Simple::facades() so you do not have to deal with Long\Class\Namespace\Chains::toDo()->stuff() among other benefits.
  • Has a host of powerful features shown in the documentation.

The Starter Theme:

  • Is built around the WP Emerge framework.
  • Does not come with opinionated predefined css classes or styles – it comes with styling tools instead.
  • Includes automatic sprite generation.
  • Includes separate CSS and JavaScript bundles for the front-end, administration, login pages and the Gutenberg editor in a single build step.
  • Includes WPCS, ESLint and Stylelint for all your linting needs.
  • Comes with an automatic, fool-proof cache breaker for your assets.
  • Has an organized and clean directory structure.
  • Comes with a lightweight CLI tool which bootstraps common use cases.
  • For a full feature list check out the documentation.

How it began

The projects, which I did at one of my previous employers, were all using WordPress as a CMS for clients who had or wanted custom designs and a lot of custom functionality – online stores with special product customizations, EXPOs with specific booth bookings, crowdfunding sites, learning management systems – you name it. One day I was asked to do a peer review on a random project to find out how we can improve the overall quality of our code and if there are any common problems that we can solve for all projects.

The results from that peer review were the push I needed to finally sit down and find a proper solution to a whole bunch of development painpoints I’ve had with WordPress over the years.


The MVC design pattern is still considered to be one of the best tools in a web developer’s toolbox and for good reason. Unfortunately, WordPress does not make use of it mostly due to, what I believe are, historical reasons – this omission bears a high cost in terms of maintanability, testability and developer happiness. Take a look at wp-login.php and you will see what I mean.

Models should hold your business logic and recreating WordPress’ business logic in models is neither practical nor very helpful so WP Emerge does not focus on that. Instead, it provides controllers and views with modern tooling around them to streamline the development process and promote encapsulation of your business logic.


The Rewrite API is clunky at best – it requires regular expressions for common use cases, is limited to public query vars only, having multiple endpoints can get interesting when some of them can have empty values or when you want them to have a strict order, and more.
Wouldn’t it be better if we could specify parameters in placeholders without resorting to regular expressions, have access to the full power of WP_Query and even the ability to add logic to the whole thing? Wouldn’t it be much better if we had something like this:

Router::get( '/cars/{make}/{model}/{year}/', 'App\\Cars\\CarController@index' )
    ->query( function ( $query_vars, $make, $model, $year ) {
        return [
            'post_type' => 'car',
            'tax_query' => [
                    'taxonomy' => 'car_make',
                    'field' => 'slug',
                    'terms' => $make,
                    'taxonomy' => 'car_model',
                    'field' => 'slug',
                    'terms' => $model,
                    'taxonomy' => 'car_year',
                    'field' => 'slug',
                    'terms' => $year,
    } );

Well … now we do! And, we don’t even need to flush the rewrite rules! This is just a taste – we can do so much more, like switching what controller handles a page based on its assigned template:

Router::get( ['post_template', 'template-about-us.php'],
    'App\\About\\AboutController@index' );

… or limiting access to certain routes to authenticated users only:

Router::group( '/dashboard/', function( $group ) {
    $group->get( '/my-notifications', ... );
    $group->get( '/my-profile', ... );
    $group->get( '/my-orders', ... );
} )->add( AuthenticationMiddleware::class );

While this can be obvious to developers with experience outside of WordPress, it can be overwhelming for the rest, which is why WP Emerge’s integration is incremental – you can implement it only on the pages you need and even in legacy projects.

Template Engine

WordPress does technically have a template engine – good ol’ PHP. After all, PHP was conceived as a template engine that outgrew its original purpose but this doesn’t mean that it’s the best there could ever be, though. Proof of this are themes like Sage that uses Blade as its template engine or frameworks like Timber that uses Twig instead. Every choice has a set of tradeoffs – Blade favors developer agility while Twig can be exposed to untrusted users with no risks, for example (this is not an extensive comparison by any stretch of the imagination).

Instead of imposing a preference, WP Emerge exposes a common API for template engines. By default, it uses PHP the same way WordPress does, but with a few extra tools. In addition, there are external packages like htmlburger/wpemerge-blade and htmlburger/wpemerge-twig which allow you to replace the default behavior with a template engine of your choice. You can even use a mix by taking advantage of the built-in NameProxyViewEngine which delegates rendering to different template engines based on what file is being loaded.

… and more

The above is just a small set of features that WP Emerge has but they are crucial as they provide a stable base for a whole lot more that was previously not easy or practical to implement like testable request handling, more powerful error handling and reporting, middleware, view composers etc.

In summary

WP Emerge is by no means the cure to every ill but it is a major improvement and it continues to get better thanks to the help of the open source community.
Be sure to check out the documentation which goes over all features and how to use them, submit issues and pull requests over at GitHub and join me in the Gitter Lobby for a quick chat, if you feel like it.

Can’t wait to see what you can build with WP Emerge!

Comments are closed.