WP Emerge 0.16.0: What’s new

by Atanas Angelov | May 23rd, 2020 | Releases

This release marks a major milestone in WP Emerge’s evolution. A significant portion of the framework, app core and starter theme have been reworked and refactored to improve performance, extensibility, stability and multi-instance use.
While there are a number of breaking changes in this release, no further major changes are expected before 1.0 is shipped!

Getting started:
Starter Plugin
Starter Theme

Quick Summary:

  • An official WP Emerge Starter Plugin is now available!
  • [Framework] Facades have been replaced with a new App class which has static aliases for each facade.
  • [Framework] The new App class allows several instances to live side by side allowing multiple plugins to use WP Emerge at the same time.
  • [Framework] WPEmerge\*() functions are now App::*() aliases which are swappable during testing.
  • [Framework] Added named routes.
  • [Framework] Improved configuration and extensibility.
  • [Framework] Simplified internals.
  • [Framework] Improved overall performance.
  • [Theme/Plugin] Added an automatically generated SVG sprite (props @paulomfr).
  • [Theme/Plugin] Added a new yarn rebrand command to automatically rename the MyApp namespace and related constant/function names.
  • [Theme/Plugin] Major improvements to the build and release pipelines.
  • [Theme/Plugin] Improved Bedrock support.

Framework Breaking Changes

  • Facades have been removed entirely. While very convenient to use, facade classes ultimately made having multiple WP Emerge instances running alongside each other impossible.
    Accessing your various services statically is now done via an App class.
    Refer to the updated documentation to learn where this new app class comes from.

    • Application is now \App.
    • Csrf is now \App::csrf().
    • Flash is now \App::flash().
    • OldInput is now \App::oldInput().
    • Response is now \App::responses().
    • Route is now \App::route().
    • View is now \App::views().
    • ViewEngine has been removed – pass it as a constructor dependency if you need it.
    • WPEmerge\response() is now \App::response().
    • WPEmerge\output() is now \App::output().
    • WPEmerge\json() is now \App::json().
    • WPEmerge\redirect() is now \App::redirect().
    • WPEmerge\view() is now \App::view().
    • WPEmerge\error() is now \App::error().
    • WPEmerge\render() is now \App::render().
    • WPEmerge\layout_content() is now \App::layoutContent().
    • WPEmerge\run() is now \App::run().
  • The new App class makes it possible to have several WP Emerge instances workign side-by-side which was critical in order to support WP Emerge usage in plugins – check out the WP Emerge Starter Plugin below.
  • The new App class makes testing significantly easier as you can mock any and all aliases during testing:
    // Since we don't want to test WP Emerge internals,
    // we can overwrite them during testing:
    \App::alias( 'view', function ( $view ) { return $view; } );
    // or we can replace the entire app instance:
    \App::setApplication( new MyMockApplication() );
  • The Blade and Twig extensions now use the new WP Emerge generic cache directory configuration option by default – see “What’s New” for more information.
  • \WPEmerge\Requests\RequestInterface now extends Psr\Http\Message\ServerRequestInterface.
  • \WPEmerge\Requests\Request is now PSR-7 compatible with Psr\Http\Message\ServerRequestInterface.
    Several methods have been affected:

    • Request::get() is now Request::query().
    • Request::post() is now Request::body().
    • Request::cookie() is now Request::cookies().
    • Request::headers( $key, $default ) will now return an array of header values if $key is specified or an associative array of arrays of values otherwise.
      If you wish to get the value for a header as a single string use Request::getHeaderLine( $key ) instead.
  • \WPEmerge\Routing\RouteInterface::handle() has been replaced with a new getHandler() method. \WPEmerge\Routing\Route class has been updated to match.
  • 'routes' configuration value structure has been altered slightly to allow you to override the default attributes.
    // Before:
    'routes' => [
      'web' => 'web.php',
      'admin' => 'admin.php',
      'ajax' => 'ajax.php',
    // After:
    'routes' => [
      'web' => [
        'definitions' => 'web.php',
        // Optional:
        'attributes' => [ ... ],
      'admin' => [
        'definitions' => 'admin.php',
        // Optional:
        'attributes' => [ ... ],
      'ajax' => [
        'definitions' => 'ajax.php',
        // Optional:
        'attributes' => [ ... ],
  • The App Layout comment annotation for PHP views has been changed to just Layout.
  • Removed Response::view() – use \App::view() instead.
  • Application::getContainer() is now \App::container().
  • NameProxyViewEngine::__construct() signature has changed.
  • ErrorHandle::__construct() signature has changed.
  • Various other internal classes have had their constructor signatures changed.
  • The 'whoops' key in the container has been changed to 'Whoops\Run' (\Whoops\Run::class).

What’s New


  • Added named routes.
    You can now assign unique names to your routes and then refer to them to generate a route url:

    // Adding a name to a route:
      ->url( '/dashboard/{user}' )
      ->name( 'user-dashboard' )
      ->handle( ... );
    // Getting a route URL even with arguments:
    App::routeUrl( 'user-dashboard', [ 'user' => 123 ] );
  • There is now a new 'cache' configuration key which allows you to override the default directory which extensions should use for caching purposes.
    The default value is {Uploads Directory}/wpemerge/cache.
  • You can now get the current route instance from inside middleware or controllers using $request->getAttribute( 'route' ).
  • You can now get the current route arguments from inside middleware or controllers using $request->getAttribute( 'route_arguments' ).
  • You can now specify middleware at the controller level, with options to specify which methods that middleware should apply to:
    use WPEmerge\Middleware\HasControllerMiddlewareInterface;
    use WPEmerge\Middleware\HasControllerMiddlewareTrait;
    class MyController implements HasControllerMiddlewareInterface {
      use HasControllerMiddlewareTrait;
      public function __construct() {
        $this->middleware( 'middleware1' );
        $this->middleware( 'middleware2' )->only( 'method1' );
        $this->middleware( 'middleware3' )->except( 'method2' );
  • A new \Whoops\Handler\PrettyPageHandler::class key is available in the container which provides access to the Whoops error screen instance. Useful if you wish to blacklist environment values from appearing e.g.:
    // Hide the MYSQL_PASSWORD from the error page:
    $container[ \Whoops\Handler\PrettyPageHandler::class ]
    ->blacklist( '_ENV', 'MYSQL_PASSWORD' );
  • View composers are now applied to top-most templates loaded by WordPress even when a route is not active.

  • PHP mixin classes are now shipped with the framework which help IDEs detect built-in Application aliases.
  • You can now configure default route attributes for every group (web, admin, ajax) via configuration.
  • A WPEMERGE_VERSION constant has been added to provide easy programatical access to the currently loaded WP Emerge version.
  • Added a 'debug'->'enable' configuration option allowing you to override the debug status of WP Emerge. The value defaults to the value of WP_DEBUG.
  • Added a new 'view_composers' configuration option which gives control over view composer settings. Currently allows you to adjust the default namespace for view composer classes.
  • Action name can now be passed to the csrf middleware (e.g. ‘csrf:my_nonce_action_goes_here’).
  • Errors caught by the ErrorHandler class will now be logged to debug.log as well.
  • Added a new App::closure() helper which gives static access to container services. Allows taking advantage of the service container outside of WP Emerge (e.g. for REST API handling).
  • Query filters can now be applied to custom route conditions as long as they implement the new \WPEmerge\Routing\HasQueryFilterInterface interface.
  • Admin and AJAX error responses will not attempt to load error-admin.php and error-ajax.php, respectively, falling back to error.php if not available.
  • Simplified internals.
  • Improved overall performance.
  • Removed the autoloaded load.php and functions.php files.
  • Fixed duplicate headers in certain cases (htmlburger/wpemerge-theme#35).
  • Fixed extendConfig() merging indexed arrays incorrectly.
  • Fixed 'get_header', 'get_footer' and similar actions being called twice when using Blade views and WooCommerce.
  • Fixed Url::getPath() not always producing the expected result.
  • Fixed ErrorHandler not outputting displayed errors to debug.log when in debug mode.

Starter Plugin

  • Introduced the WP Emerge Starter Plugin.
    Similarly to the starter theme, this project alows developers to create powerful plugins utilizing the WP Emerge framework.
    Comes with all of the features the starter theme and more. Check out the documentation for more information.

Starter Theme

  • Added the ability to create an SVG sprite (props @paulomfr).
  • Moved views around in order to fully comply with WordPress theme requirements.
  • The theme/ directories for scripts and styles have been renamed to frontend/.
  • You can now create custom JavaScript and CSS bundles more easily by utilizing the new bundles key of the configuration.
  • Added recommended steps to follow to prepare to publish your project – https://docs.wpemerge.com/#/starter/publishing
  • Added a new yarn rebrand command to automatically rename the MyApp namespace and related constant/function names.
  • yarn dev has been split into two:
    • yarn start – Does everything yarn dev did with the exception of reloading the page.
    • yarn hot – Does everything yarn start does but also includes hot module replacing.
  • Browsersync has been replaced with Webpack Dev Server. Proxying your website in yarn hot mode is no longer required.
  • yarn release has been overhauled and will now:
    • No longer affect your working directory.
    • Generate a wpemerge-release directory of your production-ready project.
    • Generate a zip of the production-ready directory which can be uploaded via the WordPress theme UI.
  • yarn release will now use an authoritative classmap which improves autoloading performance.
  • yarn release will now remove all non-whitelisted options from the production config.json file. The whitelist is found in the release.configWhitelist key of config.json itself.
  • yarn build now also produces unminified bundles in order to support SCRIPT_DEBUG mode.
  • The release.include key in config.json now accepts globs.
  • config.json.dist has been updated with new required keys.
  • CSS media queries are now combined to further reduce CSS bundle size.
  • Replaced UglifyJS with Terser which produces smaller bundles.
  • Fixed config.json being parsed at runtime instead of being available as an object literal for improved performance.
  • A new wpemerge shortcut has been added to the theme and plugin to allow for easier CLI access:

    php wpemerge list
  • Moved app/setup/*.php helpers to service provider classes.

  • Added custom logo support.
  • Bedrock support has been significantly improved.
  • Added a readme.txt file.
  • Made theme WPCS 2.2.0 compliant.
  • Removed htmlburger/carbon-pagination in favor of native WordPress pagination.
  • Streamlined functions.php.
  • Updated all Node dependencies and the minimum supported Node version to 12.
  • The quickstart documentation has been updated with Bedrock-specific steps – https://docs.wpemerge.com/#/starter/theme/quickstart?id=quickstart-on-bedrock
  • Fixed a number of Theme Check issues.
  • Fixed Tailwind CSS not being autoprefixed correctly.
  • Fixed images coming from third party packages not being process (htmlburger/wpemerge#18).
  • Fixed editor styles integration (htmlburger/wpemerge-theme#47).
  • Fixed PHP 7.4 support (htmlburger/wpemerge-theme#43).

App Core (previously known as Theme Core)

  • Package has been renamed to htmlburger/wpemerge-app-core and is now shared between the starter theme and plugin.
  • Added an automatic WP Emerge version conflict checker which prevents fatal errors when 2 incompatible version of WP Emerge are required by 2 or more plugins and/or themes.
  • Facades have been removed entirely. Accessing your various services statically is now done via an App class:
    • Theme\Assets is now \App::core()->assets().
    • Theme\Avatar is now \App::core()->avatar().
    • Theme\Config is now \App::core()->config().
    • Theme\Image is now \App::core()->image().
    • Theme\Sidebar is now \App::core()->sidebar().
    • Theme has been removed as it is no longer necessary.
  • Theme::partial() has been removed as it only causes confusion. Use \App::render() instead.
  • Theme::uri() has been removed as the theme root now matches get_template_directory_uri() making the method obsolete.
  • Theme::getThemeUri() is now \MyApp::core()->assets()->getUrl().
  • Theme::getAssetUri() is now \MyApp::core()->assets()->getAssetUrl().
  • The following actions/filters have been renamed:
    • app_favicon_uri is now wpemerge_app_core_favicon_url
    • app_sidebar_context_post_id is now wpemerge_app_core_sidebar_context_post_id
    • app_get_title is now my_app_get_title.
  • The following actions/filters/meta have been renamed:
    • _app_custom_sidebar is now _custom_sidebar.
  • The following container keys have been renamed:
    • wpemerge_theme.assets.manifest is now wpemerge_app_core.assets.manifest.
    • wpemerge_theme.assets.assets is now wpemerge_app_core.assets.assets.
    • wpemerge_theme.avatar.avatar is now wpemerge_app_core.avatar.avatar.
    • wpemerge_theme.config.config is now wpemerge_app_core.config.config.
    • wpemerge_theme.image.image is now wpemerge_app_core.image.image.
    • wpemerge_theme.sidebar.sidebar is now wpemerge_app_core.sidebar.sidebar.
    • wpemerge_theme.theme.theme is now wpemerge_app_core.app_core.app_core.


  • make:* commands now work correctly when you specify a class with a namespace.
  • make:controller now accepts a --type parameter with one of these values: web, admin or ajax.
  • Added a new make:service-provider command.
  • Updated installed Tailwind version to ^1.1.2.
  • Removed the make:facade command.
  • Fixed Carbon Fields installation.

Blade Extension

  • Improved WooCommerce support.
  • Updated the illuminate/view package version to 7.14.0.
  • Filtering core templates in the Blade extension is now off by default. Refer to the new 'filter_core_templates' config option in the extension README.md.

Comments are closed.