The client *

Goals of Web Efforts

• Use WordPress for content management

  Existing mix of ColdFusion, old WordPress, etc...

• Refactor existing site functionality

  Former development efforts were of varying quality

• Add functionality to satisfy new requirements

  Provide better tools to adapt to the market

• Improve compliance

  Growing number of regulations that need to be addressed

Sites differ in technology, structure & scope

Individual sites are complex

Lots of custom content...

lots of custom code!

Challenges

• Vast scope

  Large number of sites with lots of custom behavior

• Moving target

  Mergers & acquisitions keep number of sites growing

• Difficult maintenance

  Websites in differing states scattered across differing infrastructures

Primary Goals of Architecture Proposal

1. Best practice: There needs to be a standardized way of accessing different subsystems, so that they can communicate with each other.

   » Business Goal: Have code be independent of global state or file system layout.

2. Best practice: There needs to be a standardized way of instantiating specific implementations of a subsystem referenced by unspecific interfaces.

   » Business Goal: Isolating needed code changes to a single subsystem at a time.

3. Best practice: There needs to be an application-wide logging mechanism. The application should not need to know about the specific implementation of the logging system. The log data needs to be freely routable to different storage & processing systems without changes to the application itself.

   » Business Goal: Being able to retrace errors.

   » Business Goal: Monitoring for exceptional scenarios.

4. Best practice: There needs to be a persistent messaging queue that decouples event initiators from event handlers.

   » Business Goal: Maintaining transaction integrity.

   » Business Goal: Allowing events to cross session boundaries.

Secondary Goals of Architecture Proposal

1. Challenge: The number of sites as well as their respective state and structure is constantly changing.

   » Business Goal: Deploying architecture incrementally.

   » Business Goal: Running both new code and legacy code side-by-side.

2. Challenge: Some subsystems are not integrated into WordPress.

   » Business Goal: Running architecture code outside of WordPress framework.

3. Challenge: Some subsystems can not directly be changed.

   » Business Goal: Injecting and decorating without modifying source.

Site stack

• Composer stack based on WP-Starter

  https://github.com/wecodemore/wpstarter

• Environment configuration provided through .env files

  https://github.com/vlucas/phpdotenv

• Third-party plugins pulled in via SatisPress

  https://github.com/blazersix/satispress

composer.json   (extract)

{
    "name": "danielstrading/danielstrading.com",
    "require": {
        "php": ">=7.0",
        "gaa/gaa-custom-login": "^1",
        "gaa/gaa-featured-products": "^1",
        "gaa/gaa-gravity-forms": "^1",
        "gaa/gaa-log": "^1",
        "gaa/gaa-member-area": "^1",
        "gaa/gaa-membership": "^1",
        "gaa/gaa-services": "^1",
        "gaa/gaa-sitemap": "^1",
        "gaa/gaa-tracking": "^1",
        "gaa/gaa-virtual-services": "^1",
        "gaa/gaa-webinars": "^1"
        [ ... ]
    }
}
            

.env   (extract)

#------------------------------------- SITE SETTING -------------------------------------#
# Code identifying the current site. This controls what site-specific configuration to
# load through the Config Mapper.
GAIN_SITE=DT

#--------------------------------- ENVIRONMENT SETTING ----------------------------------#
# Current environment that the site runs in. This controls what environment-specific
# configuration to load through the Config Mapper.
WORDPRESS_ENV=development

#----------------------------- MANDATORY DATABASE SETTINGS ------------------------------#
# Database connection settings for the WordPress database.
DB_NAME=<database name>
DB_USER=<database user>
DB_PASSWORD=<database password>

[...]
            

Main Components

• Auto-wiring Dependency Injector

  Central control over instantiations.

• Service Locator

  Inter-plugin dependency resolution.

• Config Mapper

  Site- and environment-specific customizations.

• Log Manager

  Central control over logging and notifications.

• Message Bus   (work in progress)

  Decouple business processes from web server.

"Auto-wiring Dependency Injector"

• "Auto-wiring Dependency Injector"

  An object instance or scalar value that the current code needs to be able to work.

• "Auto-wiring Dependency Injector"

  The dependency is not fetched from the current code itself, but injected from the outside.

• "Auto-wiring Dependency Injector"

  The injection is done recursively, resolving the dependencies's dependencies, and so on...

Auto-wiring Dependency Injector

• Sole source of instantiations.

  For all types that are not considered to be "newable"*, the Injector takes care of the instantiation.

• Allows coding against interfaces.

  Consuming code never needs to know about the specific implementations to use. It only requires any object fulfilling the interface it needs and then just uses that without needing additional checks.

• Allows overriding default implementations.

  Through the use of the Config Mapper, implementations can be overridden globally, per plugin, per site or per environment.

Service Locator

• Each site has multiple Service Providers.

  A Service Provider is often conceptually equivalent to a plugin. A plugin can however contain more than one Service Provider.

• Each Service Provider has one or more Services.

  A Service is a one coherent grouping of functionality.

• Each Service Provider has any number of Dependencies.

  Each Dependency is another Service or Virtual Service.

• A Service Provider only registers its Services once all of its Dependencies are met.

  As this is checked each time a new Service Provider is loaded, this takes care of both dependency management and loading order.

Service Locator Example

                interface CustomerDashboard { public function render( array $context = [] ) : string; }
            

                final class CustomerDashboardServiceProvider extends AbstractServiceProvider {
                    public function get_name()         { return 'Customer Dashboard'; }
                    public function get_dependencies() { return [ 'IsLoggedIn', 'CustomerDatabase' ]; }
                    public function get_services()     { return [
                        'CustomerDashboard' => CustomerDashboard::class,
                    ]; }
                }
            

                <h2>Customer Dashboard</h2>
                <div class="customer-dashboard">
                    <?= Services::get( 'CustomerDashboard' )->render( [ 'user_id' => $id ] ) ?>
                </div>
            

Config Mapper

• Reusable code and business data are decoupled through Config Files.

  A Config File contains all the data that is not 100% reusable across all projects. It also adds information to the Injector to map interfaces to implementations.

• The Config Mapper assembles a final Config File.

  When the Dependency Injector asks for a specific Config File to feed as a dependency into a class to instantiate, the Config Mapper assembles the correct for the current context.

• Same code, different configuration per site.

  All the general-purpose code is shared as is. Fix the bug for one site, and you fix it for all the sites.

• Configure your code per environment.

  No need for conditional code, just use the implementations that fit the environment.

Config Mapper Example 1/2

                GAIN_SITE=DT
                WORDPRESS_ENV=development
            

                $config = Config::get( 'plugin-name', PLUGIN_DIR, __NAMESPACE__ );
            

Config Mapper Example 2/2

                        class Notifier { public function __construct( EmailSender $sender ); }
                    

                        GAIN_SITE=DT
                        WORDPRESS_ENV=production
                    

                        GAIN_SITE=DT
                        WORDPRESS_ENV=development
                    

                        // File: config/dt-production.php
                        return [ Injector::STANDARD_ALIASES => [
                            'EmailSender' => SendGridEmailSender::class,
                        ] ];
                    

                        // File: config/dt-development.php
                        return [ Injector::STANDARD_ALIASES => [
                            'EmailSender' => NullEmailSender::class,
                        ] ];
                    

                        Services::get( 'Notifier' )->send( $message );
                    

                        [2017-03-18 12:15] [DT|production] Notifier.INFO:
                            Sent email through SendGrid.
                    

                        [2017-03-18 12:15] [DT|development] Notifier.INFO:
                            Skipped sending email.
                    

Log Manager

• Entire code base is only coupled to the PSR-3 interface*.

  None of the consuming needs to be concerned about how the logger is implemented or where to get it from.

• Safe default to allow the logger to be used everywhere.

  By default, the Psr\Log\LoggerInterface is mapped to a NullLogger.

• Centralized control from outside of consuming code.

  A separate plugin can provide the configuration for all logging to be routed as needed.

• Routing is based on the calling code's namespace.

  Any namespace level can be individually targeted and re-routed or pre/post-processed as needed.

Log Manager Example

                namespace Deeply\Nested\Namespace;
                class ClassA { public function do_work() {
                    $this->logger->debug( 'Debug Class A' );
                    $this->logger->warning( 'Warning Class A' );
                } }
                class ClassB { public function do_work() {
                    $this->logger->debug( 'Debug Class B' );
                    $this->logger->warning( 'Warning Class B' );
                } }
            

                'Deeply\Nested'                  => [ Handler::LEVEL => LogLevel::INFO  ],
                'Deeply\Nested\Namespace\ClassB' => [ Handler::LEVEL => LogLevel::DEBUG ],
            

                ( new Deeply\Nested\Namespace\ClassA )->do_work();
                ( new Deeply\Nested\Namespace\ClassB )->do_work();
            

                [2017-03-18 12:18] [DT|development] Deeply\Nested.WARNING: Warning Class A.
                [2017-03-18 12:19] [DT|development] Deeply\Nested\Namespace\ClassB.DEBUG: Debug Class B.
                [2017-03-18 12:19] [DT|development] Deeply\Nested\Namespace\ClassB.WARNING: Warning Class B.
            

Message Bus (WIP)

• Decouple business processes from the current web request.

  When a visitor makes a request, it is passed on to the message queue as a Command or Event (and not processed by the WordPress process). Errors in one don't impact the other.

• Simplifies transactional integrity.

  Requests persisted to the message queue cannot get lost.

  If the worker cannot successfully complete a process, it can retry until a certain threshold has been reached, and then notify about the failure.

  Failed processes can be re-run once the error condition has been eliminated.

• Serves as a transparent bridge between processes and servers.

  The web server on which a request is made does not need to be the same server that will do the actual processing. It only needs to know that the Message Bus has accepted the request and trust it will be handled.

  This allows for better scalability, by offloading worker processes to different servers and letting the Message Bus act as load balancer.

Message Bus Example

                        class SubscribeToNewsletter implements Command {
                            public function __construct( Email $email ) {
                                $this->email = $email; } }
                    

                        Bus::registerCommandHandler(
                            SubscribeToNewsLetter::class,
                            NewsletterSubscriptionHandler::class );
                    

                        add_action( 'submit_newsletter_form',
                            function ( $email ) {
                                // Trust the Bus to handle actual work.
                                CommandBus::handle(
                                    new SubscribeToNewsletter( $email )
                        ); } );
                    

                        class NewsletterSubscriptionHandler {
                            public function handle( Command $command ) {
                                // Persist to database.
                                EventBus::notify(
                                    new NewSubscriber( $command->email )
                        ); } }
                    

                        // Just confirm reception and exit process.
                        echo View::render(
                            'thank-you',
                            [ 'email' => $email ]
                        );
                    

                        $handlers = [ AddToCRM::class,
                                      RegisterDemoAccount::class,
                                      SendWelcomeEmail::class ];
                        foreach ( $handlers as $handler ) {
                            Bus::registerEventHandler(
                                NewSubscriber::class, $handler );
                        }
                    

Benefits of the new architecture

• Fast site on-boarding

  Simple sites can be moved to the architecture and gain all of its benefits within weeks

• Robust code

  Strong type-hinting eliminates a lot of bug sources

• Flexible code

  Coding against interfaces makes changes easy and avoids side-effects

• Reusable code

  Entire codebase reusable across all sites, reducing maintenance effort

• Fast error detection

  Extensive logging, notifications and separations of concern make debugging less painful

Use Config Files!

The config files turn random business-specific code into data-driven business logic that is reusable across multiple sites.

In this way, we can turn all of our custom functionality into resuable Composer packages that can be required by each site on an as-needed basis.

Use Dependency Injection!

The auto-wiring dependency injector lets us defer decisions about implementation details to later code. Our business logic is clean, elegant and easy to understand and debug.

Coupled with the config files, this also allows us to provide environment-specific setups without muddling everything up with conditional code.

Use WordPress for its Strengths, Delegate the Rest!

We went through great lengths to not negatively impact the content editing experience, and even enhance it to improve the productivity of the marketing team.

However, we moved all non-CMS stuff that WordPress was doing into different subsystems optimized for that purpose.

Try it yourself!

I planned on having a scaffolding tool ready for WordCamp London for you to roll your own site backbone.

However, time constraints didn't quite allow for this.

For now, head over to the following URL to get an overview of the public packages, and to get updates about when the scaffolding tool will be ready:

https://www.alainschlesser.com/bright-nucleus-architecture/

Big thanks go to both GAIN Capital/Global Asset Advisors and Gamajo Tech for making it possible to release most of the architectural code into open source!