Alain Schlesser

Using Bento Components in Gutenberg Blocks

Fri, 08 Apr 2022 00:00:00 GMT

I have spent the weekend of March 19th to 21st at the CloudFest Hackathon in Rust, where I had submitted a project together with Pascal Birchler (@swissspidy). It was lots of fun and producing many interesting insights for me personally as well as for the team, so I'd like to share a few of my impressions here.

Pascal Birchler & Alain Schlesser on stage presenting the Bento + WordPress project.

What is the Cloudfest Hackathon?

The global cloud computing industry comes together each year in the Europa-Park Resort in Rust to celebrate the Cloudfest (formerly World Hosting Days). This event is happening in an amusement park that is still closed off to the public, with all of the attractions being reserved for the attendees! 😁

Leading up to the Cloudfest on the weekend immediately prior, there is traditionally the Cloudfest Hackathon, where open source enthusiasts join forces with industry partners to work on exciting projects.

The last two planned editions of this hackathon had to be canceled due to the pandemic, so I was even more eager this time to get together with the other participants and have a few days of social fun in a creative setting.

What is Bento?

Bento is a relatively new high-performance web components library that makes it easy to optimize your web properties for a great page experience. It is officially governed through the OpenJS Foundation and was initially conceived to make the performance insights and engineering expertise of the AMP project available to more people and with fewer strings attached. Bento components are self-contained and can be used in a gradual mix-and-match approach, as opposed to the all-or-nothing proposition that the AMP runtime tries to enforce.

Bento components are packaged as React or Preact components for a seamless integration into any framework using such a stack. However, they are also provided as standardized Web Components so that they can be used anywhere else where (P)React might not be available.

Why would Bento be a good fit for Gutenberg Blocks?

The WordPress block-based editor, or Gutenberg, lets site owners assemble a page layout via "blocks". These blocks are designed with two different contexts in mind: an interactive editing representation that lets you manipulate the block to your liking within the admin backend, as well as a rendered frontend representation that gets persisted into the database and is shown to visitors.

This duality, in its simplest form, is represented by the two main functions that each block needs to provide to properly exist within Gutenberg:

import { useBlockProps } from '@wordpress/block-editor';

const blockSettings = {
    apiVersion: 2,

    // The edit function renders the block in its editable representation.
    edit: () => {
        const blockProps = useBlockProps();

        return Your block in the editor.;
    },

    // The save function renders the block in its final frontend form.
    save: () => {
        const blockProps = useBlockProps.save();

        return  Your block on the frontend. ;
    };
};

The "Edit" context is what the block editor shows within the WordPress admin backend. It is a fully interactive editing environment powered by React. This allows us to use the React version of the Bento web components within the editor. These React components can be intertwined with the Gutenberg React components in seemingly endless and sometimes quite surprising ways.

The "Save" context is regular frontend markup. This is the snippet of HTML that will be stored in the content as it is persisted to the database. This, on the other hand, is a perfect fit for the web components that Bento can be compiled into. Instead of the markup being a very complex hierarchy of nested divs and other elements to power such a component, it will be the simplest possible representation in the form of a custom HTML element, like . This has the advantage that fewer internals bleed into the database, making upgrades to the actual components smoother and less expensive.

Goal of the Hackathon

Pascal & I did not have a very well-defined goal when introducing the project, with the following excerpt as the stated goal leading up to the event:

The goal would be to create a starter template that makes it easy to quickly set up a WordPress website that has excellent Page Experience scores right out of the gate, by powering Gutenberg blocks via a solid Bento components foundation.
https://www.cloudfest.com/project/bento-wordpress

Once our group was assembled and started discussing the project, though, the team was quick to agree on an approach and a deliverable to target: a landing page for a fictitious hackathon powered by a Gutenberg full-site editing (FSE) theme and custom blocks using Bento components.

This would force us to have a practical application that we were aiming for, and it allowed us to split up the tasks in a very pragmatic way, letting us work in parallel for most of the hackathon.

Room full of busy hackathon participants.

Bento Components that were Implemented

Most Bento components were a 1-to-1 mapping into Gutenberg blocks. However, some components required more than one block to make sense in terms of their UX. The following table summarizes what we ended up with during the course of the hackathon.

HTML Element(s)	React Component(s)	Block(s)
	BentoAccordion, BentoAccordionSection, BentoAccordionHeader, BentoAccordionContent	bento/accordion, bento/accordion-section
	BentoBaseCarousel	bento/carousel
	BentoDateCountdown	bento/date-countdown, bento/countdown-days, bento/countdown-hours, bento/countdown-minutes, bento/countdown-seconds
	BentoFitText	bento/fit-text
	-	(filter)
	(template part)	bento/sidebar
	BentoSocialShare	bento/social-share
7 Bento components		11 Gutenberg blocks

All of these 11 blocks combine to power the landing page that we created for this fictitious hackathon. Note that we started with a completed empty theme that only had a theme.json file to start with. This theme was extracted from the end-to-end tests of the Gutenberg source repository.

You can see this page for yourself and experiment with the scrolling, the image lazy loading, etc. by heading to the following URL:

👉 bit.ly/bento-wp 👈

Example Component: Bento Fit-Text

I'll use one of the simpler components to demonstrate the interactions between Bento and Gutenberg: the component.

The Fit-Text component provides a way to render arbitrary text into a block container in such a way that it always properly fills its container. It does so by adapting the font size dynamically, within parametrizable minimum and maximum limits.

To provide a useful user experience, this component did not only require inspector controls to set the minimum and maximum font size and a way to provide the text to show - it also needed a way to configure the height of the container in an intuitive way.

To achieve this, we combined the Bento component with a component to make it typable, and wrapped it in a to add a draggable height control.


     {
            setLocalHeight((prevHeight) => prevHeight + delta.height);
        }}
    >

What were the Findings?

Both Gutenberg and Bento are flexible enough where it matters

We ended up with some pretty wild configurations, nesting Gutenberg blocks within Bento components that are nested in Gutenberg blocks...

We hit a single issue where something was not working as expected for Gutenberg, and a quick patch resolved that issue promptly.

Gutenberg had no trouble at all keeping parts or all of the interactivity of the Bento components alive within the live editor.

Bento on the other hand was happily accepting any Gutenberg blocks within containers like the accordion section.

Gutenberg DX is coming together

Maybe this was less of a surprise for some of the other members of the team, but for me personally, the developer experience of integrating these Components into new custom blocks was surprisingly good.

I still have trouble with finding the information I need, given the lack of up-to-date documentation for all of the new and advanced stuff that Gutenberg provides, but in this specific context, that was a non-issue - given we had members of the core Gutenberg team sitting at our table.

In the end, it was mostly a matter of finding the right React components for each of the expected user experiences and fiddling with the attributes to get them into the right spots. This made it very quick to get a first prototype going for most of these components.

Bento interactivity performance is impressive

The Bento components are based on years of engineering efforts to optimize for raw performance and hardware acceleration.

Components that have animated parts are rendered with surprising smoothness, even in the Gutenberg live editor.

The page we ended up with was not only completely unoptimized, it was also using images we dragged directly from Unsplash into the editor, with the entire thing hosted on a very slow VPS. Given that what you see on the sample page is probably the worst case scenario, we can confidently say that the performance of the Bento components is as good or even better as we hoped.

What's next?

The team already discussed next steps and will proceed to add more polish to the current implementations. We're also discussing what an appropriate structure of the plugin could look like. Do we want to have all blocks in one single plugin? Multiple plugins with individual blocks? How does this tie into the public block library?

You can keep up-to-date with our latest development efforts for this project at the following URL:

👉 bit.ly/bento-wp-repo 👈

Thanks again to the entire team that worked on this project and invested time and effort into producing a workable solution in such a short time frame! 🎉

Pascal Birchler • Alain Schlesser

Jessica Lyschik • Héctor Prieto • Marcel Schmitz • Adam Zieliński • Greg Ziółkowski

The Cost of Contribution

Wed, 20 Nov 2019 00:00:00 GMT

The following text is the script for a lightning talk I did at WordCamp US 2019. I failed to deliver the talk in the way I had planned for various reasons, so I want to give this important topic a second chance in written form.

In the summer of 2014 I started work on my first client site using WordPress, as I had just switched careers from government agent to freelance developer. I made heavy use of the WordPress Codex to learn how to solve my problems, and I found it to be vast, detailed ... and often also very bad advice.

So I thought to myself: I should blog about this and share better practices with other WordPress developers.

As I fleshed out more of my project, I started to hit bugs in the WordPress Core code. I'm not talking about exotic edge cases, but rather very obvious bugs. As I found out, these bugs were known, already had patches to fix them and were just waiting for these patches to be committed ... for 3 to 8 years or so!

So I thought to myself: I should contribute to WordPress Core to help fix those bugs in a shorter time frame.

That way of "slipping" into contribution probably sounds familiar to a lot of you...

After a while, I started questioning my choice of the platform, as WordPress was not the development tool I had hoped it would be, mainly because it prioritizes end-users over developers (and for a valid reason). And just when I considered switching, I experienced the one thing that has continued to keep me in this space: the WordPress Community.

It's a community full of passioned and inspiring people, and when you come into contact with it for the first time, it can be very intoxicating - I was hooked right away!

But with time, I noticed more and more that this highly inspiring and addicting environment did have a negative long-term effect on some community members.

I witnessed stress, anxiety, and burn-outs amongst the contributors, and a lot of churn in general. So I wondered why such a seemingly positive environment and noble common cause could have such a bad outcome for some people.

I believe that all of this can be traced back to a very simple root cause: Cost.

Everything we do comes with a cost attached. It is usually the combination of several different costs: the cost of energy for operating our body and mind, the cost of opportunity for not doing something else, the financial cost of travel and accommodation for attending an event, and so on and so forth.

The best way to cover cost, in general, is money. It is the tool best fit for the job, as it can be easily traded for other resources and is neither intrinsically valuable nor scarce on its own. It is simply an exchange mechanism for offsetting costs against each other in an asynchronous way.

In open-source projects, a lot of people are not paid for their contributions and don't receive money for covering their costs.

What they usually trade instead is time. But time is a much more scarce resource and cannot be amassed or regained.

And if you overdo this, you're spending the time that should rather go into your family or your health instead, with devastating long-term effects.

So why is it that we tend to keep contributing even to the point of hurting ourselves?

The main driving force behind this is our natural tendency towards prosocial behavior. On one hand, this is ingrained deep within us, as caring for the group means improving the chances of the group for survival - a fundamental evolutionary mechanism.

But prosocial behavior is also rooted in a principle called reciprocity. There is a hot debate going on for a while now whether true altruism really does exist, but most researchers seem to agree that when we help someone, we ultimately do it for what we get back in return. This can be a direct benefit, like gratitude or recognition, but it can also be a more subconscious reward, like helping as the fastest way to escape an uncomfortable situation, for example.

Whether we actually decide to help or not is then a matter of doing a subconscious cost-benefit analysis of the situation. Is the return we get from helping more valuable than the cost we need to invest?

So wouldn't that mean that we only contribute as long as our return outweighs the cost we invest...? ... that we'd keep ourselves automatically from overdoing it or hurting ourselves...?

Unfortunately, it's not that simple and there are many other factors at play.

When we help, our body produces serotonin, making us happy about what we did, to encourage this behavior (remember the evolution that is at play). This can lead to an addiction that is commonly known as "helper's high", where people simply cannot stop helping and do it even to their own detriment, always chasing the next helper's high.

There's another psychological effect that constantly lets us compare ourselves to our social surroundings and derive our self-esteem from how we perceive these social comparisons. Seeing other people contribute motivates us to contribute as well. Seeing other people contribute more than we do motivates us to try even harder to match this.

Also, within a given group, people tend to strive for conformity, trying to adhere to whatever the social norm seems to be for that group. What's worse, if no expectation was explicitly set to define this norm, the group members will deduce it from the perceived behavior of the group. This leads to situations where volunteer contributors, besides their regular day job, try to match the output of professional full-time contributors, because that is what they perceive as the norm in Slack. They are unaware of the large majority of people who can only be seen in Slack every few weeks or months.

Considering all of these psychological factors makes it even more important to talk about sustainability in open source contributions. People need to be aware of the costs involved, and what it means to contribute to something without hurting yourself or your family in the process.

Let's work on destigmatizing the money topic in the open-source space, as it is our best bet for making this work sustainably in the long run. It is not heroic or laudable to do too much and burn out, and we all ultimately lose because of it. We don't need a rotation of martyrs that we churn through. All we need is a constant accumulation of reasonable and sustainable efforts.

And please, if you have the feeling that someone is doing too much or putting too much pressure on themselves, absolutely do talk to them and try to address the issue. Who knows, maybe they just weren't aware that they're chasing the wrong "norm" to conform to...

Here's the video recording of the lightning talk as well, but my bad memory made a mess of the delivery, I'm afraid.

Featured image credits: Aron Visuals on Unsplash

Application <=> Server Management Protocol (ASMP)

Mon, 26 Nov 2018 00:00:00 GMT

While I was in Belgrade for WordCamp Europe, I took part in a meeting of a smaller group of core contributors to discuss the status and future of the Servehappy project. One topic we discussed was that the ideal end goal, from the end user's perspective, would be to have an automatic updating mechanism that keeps the entire server automatically up-to-date and secure. While this might be a lofty goal, we wanted to nevertheless look into what would be necessary to make this a reality.

While we can already automatically update WordPress Core, as well as plugins and themes, we cannot do the same for the components of the WordPress stack that are installed at the server level. There's currently no standardized protocol for server applications to request information about or changes to the underlying infrastructure. While we have APIs to provision such servers through code, we have no protocol or API to allow the applications that run on them to make changes after the provisioning.

I hereby suggest creating a communication protocol (tentatively called ASMP) between servers and applications that run on these servers that allows for bidirectional communication so that these two actors can coordinate.

Let's look at a few examples

As an example, think about regular users managing a WordPress site. On the WordPress "Server setup" page in the admin backend, the end user would see the current PHP and MySQL versions used by WordPress, as well as potential notifications about available updates.

The available updates are calculated by querying ASMP about the 'php' and 'mysql' components and then checking the returned ranges of supported versions against its own requirements.

When the user wants to run such an update, they click the corresponding button, which will have WordPress send an ASMP request to the server to 'set' the version of the 'php' component to the requested version.

Then WordPress can poll the ASMP state of that request to get updates. It could return states like 'queued', 'in-progress', 'completed' or 'rejected'` to let WordPress know how this is moving forward and adapt the user interface to give feedback to the user.

This would give more control to users, reduce support tickets for hosting providers and indirectly improve version distribution of the server components managed in this way.

As another example, think about developers that manage their project through a package manager like Composer or NPM. When you provision a server with a composer install instruction, you could have Composer automatically make requests to the underlying server based on the "require" statements that define the platform and extension requirements.

Composer could just as well throw an error when the server is not capable of providing the requested environment, and let the user know which components failed to resolve properly.

Guiding principles

Planning the ASMP protocol and providing reference implementations should follow a few guiding principles:

Applications can only make requests, not force any changes.
There is no guaranteed support, servers are free to only provide partial implementations.
Requests are asynchronous, they don't return responses.
State and capabilities can be queried, so that user interface and expectations can be adapted to the current server.

These guiding principles still allow for more exotic implementations, like a request to update a given component doing nothing more than creating a support ticket with required details. Hosting providers are free to choose the subset to implement and the specific way to implement it. The implementations can then grow from there and be further automated in time.

Technical details

The transport to be used could be regular HTTPS, with a server environment variable providing the host to contact for queries and requests. This environment variable would point to localhost when running on stand-alone servers, but could be deviated to centralized server for hosting providers that have more complex orchestration needs. The server environment should also contain an authentication mechanism, like a token, to make sure queries and requests can only be made from the correct server.

We should provide a reference implementation based on a common server distribution. This makes sure that it is easy for hosting providers to add support to their hosting and helps keep the experience consistent.

Also, focusing on building implementations into popular server control panels would accelerate adoption, as all servers managed through a given control panel would automatically inherit the implementation of the ASMP protocol.

What's next?

I am in the process of introducing this as a proposal to the Cloudfest Hackathon which will be held on March 23-25, 2019 in Rust, Germany. If this gets accepted, it will probably be an immediate opportunity to collaborate with major hosting/control panel providers to build a working prototype. Anyone who is interested in participating in this endeavor and willing to travel to Germany for the occasion can still apply for the hackathon.

Singletons And Shared Instances

Sat, 08 Jul 2017 00:00:00 GMT

Every once in a while, when discussing software design with fellow developers, the topic of Singletons comes up, especially in the context of WordPress development. Often times, I try to explain why these should be avoided, even though they are recognized as being a "standard pattern".

In this article, I try to go over the reasoning of why the Singleton should never be used in your code, and what alternative approaches you can use instead to solve the same problems.

What is a Singleton?

The Singleton is a software design pattern that has been described in the book Design Patterns: Elements of Reusable Object-Oriented Software by "the Gang of Four", the reference that effectively started the talk about Design Patterns as a software engineering tool.

The basic principle is that you want to ensure there can only ever be a single instance of a given class, and you provide a global point of access for it.

This is really easy to explain and understand, and for most people, the Singleton is the entry drug into the world of Design Patterns, making it the single most popular pattern.

So, given its popularity, and given the fact it is part of the reference book and was amongst the first patterns to be described and standardized, how comes that some developers decry it as an "anti-pattern"? Can it really be that bad?

Yes.

Yes, it can.

But Singletons are useful and necessary!

I notice that a lot of people confuse two related concepts, and when they say they need a Singleton, they actually mean to say they need to share a same instance of an object across different instantiations. In general, when you instantiate a class, you create a new instance of that class. But for some objects, you want to always use the same, shared instance of that object, no matter where it is being used.

But the Singleton is not the proper solution for this.

The confusion is caused by the fact that a Singleton actually combines two responsibilities in one object. Imagine having a Singleton that is being used to establish a connection to the database. Let's call it (very creatively) DatabaseConnection. The Singleton now has the following two main responsibilities:

Manage the database connection.
Manage the instantiations of the DatabaseConnection.

Responsibility 2. is what makes people pick the Singleton, but this task should actually be the responsibility of a different object.

The problem with a Singleton is not that it is shared, but that it enforces its own instantiation.

There's nothing wrong with using a shared instance. But the object you want to share is not the place to put that restriction into.

I'll show some alternative approaches of how to handle this later in the article. But first, I want to discuss what types of problems the Singleton will cause.

Problems with the Singleton Pattern

Singleton vs SOLID

First of all, and this might seem to be more of a theoretical and puristic issue than a real problem at first, the Singleton design pattern breaks most of the SOLID principles.

S stands for "Single Responsibility Principle". It should be obvious that the Singleton pattern goes against this principle, as already described above.
O stands for "Open/Closed Principle", meaning that objects should be open for extension but closed for modification. The Singleton breaks this principle because it controls the point of access, and will only ever return itself, not an extension.
L stands for "Liskov Substitution Principle", meaning that objects should be replaceable by instances of their subtypes without needing changes to the consuming code. This obviously does not work out for a Singleton, as the simple fact of having multiple differing versions of an object causes it to not be a Singleton anymore.
I stands for "Interface Segregation Principle", meaning that you should prefer many client-specific interfaces over one general-purpose one. This is the only principle that the Singleton does not directly break, but only because the Singleton does not allow for an interface to begin with.
D stands for "Dependency Inversion Principle", stating that you should depend on abstractions, not concretions. Once again, the Singleton breaks this principle, because you can only ever depend on the very concrete Singleton instance.

The Singleton pattern breaks four out of five SOLID principles! It would probably even want to break the fifth as well, if only it was able to have interfaces in the first place...

The Singleton pattern breaks four out of five SOLID principles!

It is easy to say that your code does not work or break because of some random theoretical principles. And although my personal experience has shown time and time again that these principles are amongst the most valuable and enduring guidelines you can adhere to in terms of software design, I acknowledge that just stating this as a "fact" will probably not convince a lot of people. We should look at the impact the Singleton pattern has for your immediate practical reality.

Singleton in practical use

Here are the more practical drawbacks and issues that a Singleton brings about:

You cannot have arguments passed to/injected into the constructor. As the constructor is only actually executed by the first call that hits the Singleton, and you cannot know in advance, which of the consuming code will be the first one to hit the Singleton, all consuming code would need to have the exact same set of arguments to pass to the constructor, which is both not practically feasible in most cases, and rather pointless to begin with. As a result, the Singleton renders the main mechanism of instantiation in OOP languages useless.
You cannot mock the Singleton away when testing other components that make use of it. This makes proper unit tests practically impossible, because you never have a clear isolation of the code you want to test. This problem is not even caused by the actual logic you want to test, but rather by the arbitrary instantiation restriction you wrapped it into.
As the Singleton is a globally accessible construct that is always shared across your entire codebase, it defeats any efforts for encapsulation, causing the exact same problems as global variables do. This means that whatever you try to do to get the Singleton isolated in an encapsulated part of your code, any other external code can cause side effects and produce bugs through this Singleton. Without proper encapsulation, the very principles of object-oriented programming are diluted.
If you ever have your site/app grow to the point where your DatabaseConnection Singleton suddenly needs to allow for a second, different database connection nevertheless, you're in a world of trouble. Your very architecture needs to be revised, and will probably cause large portions of your code to need a complete rewrite.
All of the tests you write that make use of your Singleton in a direct or indirect way cannot be properly reset from one test to the next. They always carry over state through the Singleton, which can produce weird behavior where your tests depend on the order they are run in or obfuscate actual bugs because of left-over state.
They only enforce their singular instantation for the current process space that is valid for the static scope. This means that you'll run into issues with multi-threading, with multiple processes or with distributed execution. This should hint to the possibility that they are just a faulty concept that simply breaks down as soon as you work in a distributed system.

Alternatives to using a Singleton

I don't want to be the person that decries everything as bad but then fails to provide viable alternatives or preferable approaches. Although I do think that you need to consider your overall architectural design to decide how best to avoid Singletons in the first place, I can think of a few common use cases in WordPress where the Singleton can easily be replaced with a mechanism that meets all requirements while avoiding most or all of the drawbacks. But before describing these, I'd like to point out why all of them are only a compromise.

There is an actual "ideal structure" for dealing with the construction of an app. The theoretical best case is one single instantiation call in the bootstrap code that builds the entire dependency tree of the complete app from the top down. This would work along the lines of this example:

Instantiate App (needs Config, Database, Controller).
Instantiate Config to inject into App.
Instantiate Database to inject into App.
Instantiate Controller to inject into App (needs Router, Views).
Instantiate Router to inject into Controller (needs HTTPMiddleware).
...

With a single call, the entire application stack would be built from the top down, injecting the dependencies as needed. The goals with such an approach:

Every object has an exact list of dependencies it needs, and should only make use of these dependencies. When something breaks, you can easily isolate the responsible code.
No tight coupling between any of the objects, all objects rely on interfaces only while using whatever implementations will be injected.
No global state. Every individual subtree in the above hierarchy would be properly isolated from the rest, without the developers being able to introduce bugs into module B while making changes to module A.

The ideal app construction is a single instantiation call that builds the entire dependency tree.

However, as good as this might sound, it is just not possible with WordPress code. WordPress does not provide any centralized container or injection mechanism, and each of the plugins/themes are loaded in an isolated way.

Keep this in mind while we discuss the possible approaches below. The ideal solution, having the entire WordPress stack be instantiated through one centralized injector, is currently out of reach as it would need to be supported by the WordPress Core. All of the approaches below will share some of the same drawbacks in differing degrees, like the fact that they hide dependencies by accessing them directly from within the logic instead of having them be injected.

Singleton code

Here is the example code for the Singleton approach that we will use as a base to compare the other approaches to:

// Singleton.
final class DatabaseConnection {

   private static $instance;

   private function __construct() {}

   // Call to get a hold of the one true instance.
   public static function get_instance() {
      if ( ! isset( self::$instance ) ) {
         self::$instance = new self();
      }

      return self::$instance;
   }

   // Actual logic code mixed in with the instantiation mechanism.
   public function query( ...$args ) {
      // Execute query and return results.
   }
}

// Consuming code.
$database = DatabaseConnection::get_instance();
$result   = $database->query( $query );

I didn't include all of the implementation details that Singletons are often loaded with, as they don't add anything to the theoretical discussion.

Using Factories

In most cases, the easiest way to defuse your problems with Singletons is to use the Factory pattern instead. A Factory is an object that has the instantiation of objects as its single responsibility. Instead of having a DatabaseConnectionManager that takes care of its own instantiation via a get_instance() method, you'll have a DatabaseConnectionFactory that can hand out instances of a DatabaseConnection object. In general, the Factory would always hand out new instances of a requested object. But it can decide, based on the requested object and the context, whether to hand out new instances or to always share one instance only.

Regarding the naming, you might think that this looks more like Java code than PHP code, so feel free to stray away from a too strict (and thus lazy) naming convention and name the Factory in a more straightforward and creative way.

Example code for the Factory approach:

// Factory.
final class Database {

   public function get_connection(): DatabaseConnection {
      static $connection = null;

      if ( null === $connection ) {
         // You can have arbitrary logic in here to decide what
         // implementation to use.
         $connection = new MySQLDatabaseConnection();
      }

      return $connection;
   }
}

// Interface, so that we can deal with multiple implementations and properly
// mock for testing.
interface DatabaseConnection {

   public function query( ...$args );
}

// The implementation we're currently using.
final class MySQLDatabaseConnection implements DatabaseConnection {

   public function query( ...$args ) {
      // Execute query and return results.
   }
}

// Consuming code.
$database = ( new Database )->get_connection();
$result   = $database->query( $query );

You can see that the consuming code is not more difficult or verbose to write, there's only a slight nuance to it. We've opted to call the Factory Database instead of DatabaseConnectionFactory, as this is part of the API we're providing, and we always should strive to hit the right balance between logical precision and elegant consiceness.

The Factory version above gets rid of pretty much all of the drawbacks we've been identifying before, with a small exception:

Although we've removed the tight coupling to the DatabaseConnection object, we've introduced a tight coupling to the new Factory instead. This is not problematic, as the Factory is a pure abstraction, and there's a very low probability that we need to move away from the actual concept of "instantiation" at one point. If that should happen, the entire paradigm of OOP probably needs to be revised.

You'll probably start wondering now about the fact that we are not able to enforce a single instantiation anymore. Although we always hand out a shared instance of a DatabaseConnection implementation, anyone can still just do a new MySQLDatabaseConnection() and thus get access to an additional instance. Yes, that is correct, and that is actually one of the goals of getting away from the Singleton pattern. It is good to have conventions about always sharing an instance of an object. But enforcing something like this does not provide additional real-world benefits, while making basic requirements like unit testing impossible.

Using Static Proxies

A Static Proxy is another design pattern that can be used to get rid of Singletons. It introduces more tight coupling than the Factory does, but this coupling is still only tied to an abstraction, not a concrete implementation. The basic principle is that you have a static mapping of the interface, and these static calls are being transparently forwarded to a concrete implementation behind the scenes. As such, there's no direct coupling to the actual implementation, and the Static Proxy is free to decide in what ways to pick the actual implementation to use.

// Static Proxy.
final class Database {

   public static function get_connection(): DatabaseConnection {
      static $connection = null;

      if ( null === $connection ) {
         // You can have arbitrary logic in here to decide what
         // implementation to use.
         $connection = new MySQLDatabaseConnection();
      }

      return $connection;
   }

   public static function query( ...$args ) {
      // Forward call to actual implementation.
      self::get_connection()->query( ...$args );
   }
}

// Interface, so that we can deal with multiple implementations and properly
// mock for testing.
interface DatabaseConnection {

   public function query( ...$args );
}

// The implementation we're currently using.
final class MySQLDatabaseConnection implements DatabaseConnection {

   public function query( ...$args ) {
      // Execute query and return results.
   }
}

// Consuming code.
$result = Database::query( $query );

As we can see in the consuming code example, the Static Proxy creates a very short and clear API, with the drawback being that it tightly couples the code to its class signature. If used in the right places, this should not be a real problem, as the tight coupling is still to an abstraction you can directly control, and not to a concrete implementation. You are still able to swap out the specific database code with a different one as you see fit, and our actual implementation is still a completely normal object that can be easily tested.

Using the WordPress Plugin API

The WordPress Plugin API can also be used to get rid of Singletons, when they are being used for their capability of providing global access across plugins. This is a mostly clean solution within the constraints of WordPress, with the added caveat that it ties the entire infrastructure and architecture of your code to the WordPress Plugin API. Don't use this if you intend to reuse your code with different frameworks.

// Interface, so that we can deal with multiple implementations and properly
// mock for testing.
interface DatabaseConnection {

   const FILTER = 'get_database_connection';

   public function query( ...$args );
}

// The implementation we're currently using.
class MySQLDatabaseConnection implements DatabaseConnection {

   public function query( ...$args ) {
      // Execute query and return results.
   }
}

// Initialization code.
$database = new MySQLDatabaseConnection();
add_filter( DatabaseConnection::FILTER, function () use ( $database ) {
   return $database;
} );

// Consuming code.
$database = apply_filters( DatabaseConnection::FILTER );
$result   = $database->query( $query );

One of the main compromises with this code is that your architecture is directly tied to the WordPress Plugin API. If you ever plan to provide your plugin functionality for Drupal sites as well, you're facing a complete rewrite.

Another potential issue is that you're now relying on the timing of the WordPress hooks. This can introduce timing-related bugs, which are often hard to replicate and debug.

Using a Service Locator

A Service Locator is one form of an Inversion of Control Container. You'll find several references online outing it as an anti-pattern. This is true to some degree, but as we had already discussed above, all of the recommendations here have to be considered as compromises only.

The Service Locator is a container that gives you access to Services that were implemented elsewhere. The container itself is mostly just a collection of instances mapped to identifiers. More elaborate Service Locator implementations might add features like lazy instantiation or proxy generation to the mix.

// Container interface so that we can swap out the Service Locator
// implementation.
interface Container {

   public function has( string $key ): bool;

   public function get( string $key );
}

// Basic implementation of a Service Locator.
class ServiceLocator implements Container {

   protected $services = [];

   public function has( string $key ): bool {
      return array_key_exists( $key, $this->services );
   }

   public function get( string $key ) {
      $service = $this->services[ $key ];
      if ( is_callable( $service ) ) {
         $service = $service();
      }

      return $service;
   }

   public function add( string $key, callable $service ) {
      $this->services[ $key ] = $service;
   }
}

// Interface, so that we can deal with multiple implementations and properly
// mock for testing.
interface DatabaseConnection {

   public function query( ...$args );
}

// The implementation we're currently using.
class MySQLDatabaseConnection implements DatabaseConnection {

   public function query( ...$args ) {
      // Execute query and return results.
   }
}

// Initialization code.
$services = new ServiceLocator();
$services->add( 'Database', function () {
   return new MySQLDatabaseConnection();
} );

// Consuming code.
$result = $services->get( 'Database' )->query( $query );

As you might have guessed in the above example, there's still the problem of getting a hold of the reference to the $services instance. This can be solved by combining it with any of the previous three methods.

Using a Factory:

$result = ( new ServiceLocator() )->get( 'Database' )->query( $query );

Using a Static Proxy:

$result = Services::get( 'Database' )->query( $query );

Using the WordPress Plugin API:

$services = apply_filters( 'get_service_locator' );
$result   = $services->get( 'Database' )->query( $query );

This leaves us now with the question of whether we should really use the "anti-pattern" Service Locator to replace the "anti-pattern" Singleton... The problem with the Service Locator is that it "hides" dependencies. To explain what this means, you need to think about a code base that actually uses proper constructor injection throughout. In such a codebase, a quick look at the constructor of a given object immediately lets you know which other objects it depends on. If your object has access to a reference to the Service Locator, you can get around this explicit dependency resolution and fetch a reference (and thus depend on) any other object from within the actual logic. This is what people refer to when they state that the Service Locator "hides" dependencies.

However, within the WordPress context, we need to accept that we're already blocked from an ideal situation from the start. There is no technical possibility of having proper dependency injection throughout the entire codebase. This means that we have to put some compromise into the code either way. The Service Locator, although not a perfect solution, is a good fit within the such a legacy context, and at least allows you to have these "compromises" be located in one central place, instead of having your entire codebase be riddled with them.

Using Dependency Injection

If you are only working from within your own plugin and don't need to provide access to your objects to other plugins, you're in luck: you can use true dependency injection to get rid of the need to have global access to your dependencies.

// Interface, so that we can deal with multiple implementations and properly
// mock for testing.
interface DatabaseConnection {

   public function query( ...$args );
}

// The implementation we're currently using.
class MySQLDatabaseConnection implements DatabaseConnection {

   public function query( ...$args ) {
      // Execute query and return results.
   }
}

// We'll have to model the entire plugin to demonstrate this concept.
class Plugin {

   private $database;

   public function __construct( DatabaseConnection $database ) {
      $this->database = $database;
   }

   public function run() {
      $consumer = new Consumer( $this->database );
      return $consumer->do_query();
   }
}

// Consuming code.
// Also modeled as an entire class to demonstrate constructor injection.
class Consumer {

   private $database;

   public function __construct( DatabaseConnection $database ) {
      $this->database = $database;
   }

   public function do_query() {
      // Here's the actual consuming code.
      // At this point, it had an arbitrary database connection injected.
      return $this->database->query( $query );
   }
}

// Inject dependencies from the bootstrap code through the entire code tree.
$database = new MySQLDatabaseConnection();
$plugin   = new Plugin( $database );
$result   = $plugin->run();

This looks a bit more involved now, but keep in mind that we had to build a basic version of the entire plugin to demonstrate the dependency injection.

As we can't have full dependency injection across the entire app, we can at least have it within the constraints of our own plugin.

This is an example of doing the actual wiring in a manual way, by explicitly instantiating all dependencies ourselves. In a more complex codebase, you'd want to look into using an auto-wiring Dependency Injector (a specialized container) that accepts upfront configuration information and that can then recursively instantiate your entire tree in one call.

Here's an example of how this wiring would be done with such a Dependency Injector (given the same classes/interfaces as in the last example):

// Let the injector know what implementation to use for resolving the
// DatabaseConnection interface.
$injector->alias( DatabaseConnection::class, MySQLDatabaseConnection::class );

// Let the injector know it should always return the same shared instance
// for DatabaseConnection requests.
$injector->share( DatabaseConnection::class );

// Let the injector instantiate the Plugin class, which will cause it to
// recursively traverse all constructors and instantiate objects to
// resolve dependencies.
$plugin = $injector->make( Plugin::class );

Combinations

For more complex needs that are distributed across several custom and third-party plugins, you should look into combining the above approaches in ways that are adapted to your specific requirements.

As an example, I've been using the following approach with more complex client projects to get closer to the ideal approach I described further above:

Every plugin is instantiated through a centralized auto-wiring Dependency Injector.
Every plugin is a service provider that can register services with a centralized Service Locator.
Intra-plugin dependencies -> dependency injection.
Inter-plugin dependencies -> service location.
Third-party dependencies -> virtual services that wrap third-party functionality.

You can read more about this approach and see a recording of a case study talk on the Bright Nucleus Architecture page.

Conclusion

As you can see, there are several viable approaches to getting rid of your Singletons. While none of them are perfect in the WordPress context, they are all preferable to an actual Singleton, without exception.

Remember: the problem with Singletons is not that they are shared, but that they enforce their own instantiation.

If you think you know of a specific use case where the Singleton pattern is the only viable solution, please let me know, as I'd love to discuss!

OOP-NOOB Series - The Publicity Stunt

Wed, 04 Jan 2017 00:00:00 GMT

This article is part of the OOP-NOOB Series.

What Are We Talking About Here?

OOP makes use of access modifiers to control the accessibility of methods and properties. This is what allows you to use the concept of encapsulation, so that you have a public interface that consumers of your code can develop against, as well as a private implementation that needs to be treated as a black box from the outside.

Having all of your methods and properties be public generally defeats the purpose of using OOP in the first place, as most of the benefits depend on the concept of encapsulation in some form or other.

How Are Access Modifiers Being Misused

There are a few different ways people misuse OOP access modifiers in PHP, some of which are more sneaky than others.

Public Offense

The most obvious way to pull the "Publicity Stunt" is to have only public access modifiers all over the place. This results in code like this:

class PublicOffenseUser {

   public $username;

   public $password_hash;

   public function get_username() {
      return $this->username;
   }

   public function set_username( $username ) {
      $this->username = $this->validate_username( $username );
   }

   public function set_password( $password ) {
   	  $this->password_hash = password_hash( $password, PASSWORD_DEFAULT );
   }

   public function check_password( $password ) {
   	  return password_verify( $password, $this->password_hash );
   }

   public function validate_username( $username ) {
      return filter_var(
         trim( $username ),
         FILTER_SANITIZE_ENCODED,
         FILTER_FLAG_STRIP_LOW
      );
   }
}}

Although this does look like a valid class, it does not make sense as an object according to OOP principles.

First of all, the validate_username() method should probably not be part of the public interface that is provided to external consumers. This is an implementation detail, and it should be made private so that it can be changed at any time without needing to consider backward compatibility with consumers of that particular code.

What's worse though, is that the properties $username and $password_hash are public as well. So, even though we have getters and setters that try their best to enforce the consistency and integrity of these properties, any external code can directly change them at will, therefore bypassing all the integrity checks we could put in place. So, how about setting $username to -1 and $password_hash to new RuntimeException( 'Nonsense' )? The class will allow it, so the code should need to be able to handle them, right?

This might have the class stamp on it, but don't be deceived! In terms of how it works, it is closer to procedural code than to OOP. We could just as well have arbitrary variables $username and $password_hash in whatever scope, and provide procedural helper functions to deal with them.

Sins Of Times Past

There's a disguised version of the above code that looks differently, but results in the exact same behaviour:

class SinsOfTimesPastUser {

   var $username;

   var $password_hash;

   function get_username() {
      return $this->username;
   }

   function set_username( $username ) {
      $this->username = $this->validate_username( $username );
   }

   function set_password( $password ) {
   	  $this->password_hash = password_hash( $password, PASSWORD_DEFAULT );
   }

   function check_password( $password ) {
   	  return password_verify( $password, $this->password_hash );
   }

   function validate_username( $username ) {
      return filter_var(
         trim( $username ),
         FILTER_SANITIZE_ENCODED,
         FILTER_FLAG_STRIP_LOW
      );
   }
}

See, no public keywords in the code above!

However, this code behaves exactly as the version before. Why's that?

This syntax is actually PHP 4 code, from back when PHP did not yet offer a full OOP model. There were no access modifiers back then, and where you denoted a method with a simple function, you did the same for properties with var.

When you use this code in PHP 5, it offers fallbacks for the old syntax, so that old PHP 4 can still work with newer PHP versions. The only way they could provide a smooth migration from PHP 4 code to PHP 5 code was to make both the var as well as the access-modifier-less function fall back to being public. So, yes, internally, this is the exact same code than we had in the first example, with the same issues.

A Leak Of Its Own

There are some code constructs that can be very deceiving in terms of how access to properties is handled. Here's such an example:

class ALeakOfItsOwn {

   public $username;

   public $email;

   public $phone;

   private $password_hash;

   public function set_password( $password ) {
   	  $this->password_hash = password_hash( $password, PASSWORD_DEFAULT );
   }

   public function check_password( $password ) {
   	  return password_verify( $password, $this->password_hash );
   }

   public function __call( $method, $arguments ) {
      $prefix = substr( $method, 0, 4 );
      if ( ! in_array( $prefix, [ 'get_', 'set_' ], true ) ) {
         return null;
      }

      $property = substr( $method, 4 );
      if ( property_exists( $this, $property ) ) {
         switch( $prefix ) {
            case 'get_':
               return $this->$property;
            case 'set_':
               $this->$property = $arguments[0] ?? null;
         }
      }

      return null;
   }
}

As you can see above, we have made the properties $username, $email and $phone public for easy access (let's assume we don't need validation for now). The $password_hash however is private, and it comes with a setter and a "checker" method.

Then, as we are starting to get a bit too clever, we add a magic method to the class that lets it accept arbitrary method calls. The reason we do this is that we want to reduce the boilerplate code for all the getters and setters for the three public properties. So, in essence, we have replaced 6 methods with only one general-purpose one. Nice!

The problem is that, without necessarily noticing it, we completely disarmed the access modifiers of the class. So, now, even though the $password_hash is private and it has no getter, we can still just use get_password_hash() to get the property directly, as the property is then indirectly accessed from within the class. Worse yet, although we have a set_password() method that makes sure we properly hash the value first before storing it, we can just use set_password_hash() to bypass it.

So, remember that if you use magic methods like __get(), __set(), __call() or __callStatic(), it's on you to make sure you that you adhere to all the access modifier restrictions.

If you use PHP magic methods, it's on you to enforce access modifier restrictions!

Proper Encapsulation

Always remember to build your objects in a way that they provide proper encapsulation. Everything that is public is to be considered an "interface", and must have all of its inputs checked for consistency and integrity. Everything that should not be part of that public interface needs to private or protected. This then allows you to have areas of code that can be assumed to be safe from external changes and only need to be checked for integrity upon entry.

Here's an example of how our class should look:

class EncapsulatedUser {

   private $username;

   private $password_hash;

   public function __construct( $username, $password ) {
      $this->set_username( $username );
      $this->set_password( $password );
   }

   public function get_username() {
      return $this->username;
   }

   public function set_username( $username ) {
      $this->username = $this->validate_username( $username );
   }

   public function set_password( $password ) {
   	  $this->password_hash = password_hash( $password, PASSWORD_DEFAULT );
   }

   public function check_password( $password ) {
   	  return password_verify( $password, $this->password_hash );
   }

   private function validate_username( $username ) {
      return filter_var(
         trim( $username ),
         FILTER_SANITIZE_ENCODED,
         FILTER_FLAG_STRIP_LOW
      );
   }
}

There's no uncontrolled way of changing the $username or $password_hash properties from outside of the object. So, whatever checks we include in our getters and setters can be assumed to be enforced at all times. The $username property will never contain an invalid username, and the $password_hash property will always contain the hash of a password. We directly control the integrity of our object's internal state, thus reducing the number of potential bugs we can introduce into our system. This is one of the fundamental benefits that OOP offers over procedural code, so make sure you use it to your advantage.

Encapsulation is one of the major benefits of OOP over procedural code, use it!

Conclusion

Encapsulation is an important part of OOP. To make full use of it, use both access modifiers as well as other code constructs to control how and when the internal state of your objects can be changed.

Meeting The US Community

Tue, 06 Dec 2016 00:00:00 GMT

As I'm writing this, I'm on my way back home from a short trip to Philadelphia. I got to attend the PostStatus Publish conference on December 1st, followed by three days of WordCamp US. This was my first opportunity to meet the US WordPress community in their local habitat, and it was a great experience I will fondly look back to. I had not actually planned to attend this particular WordCamp (or travel so far in the immediate future), but rather decided very spontaneously to attend after a discussion with my wife and a look at the flight rates... and I'm glad I did! Here's a quick summary of the weekend that brought Discussions, Dinosaurs and Dim Sum!

Discussions, Dinosaurs & Dim Sum - A Tale Of Two (#WordPress) Conferences.

Traveling In Good Company

I was traveling with Alex Frison and Robert Windisch, partners at Inpsyde, a German agency providing enterprise-level solutions built on WordPress. During our flight from London to Philly, we actually were able to get some actual work done as well, which made us feel like "digital contortionists" in the cramped seats.

We had a lot of fun throughout the trip, and I am sad I had to leave early and couldn't join them to head over to the BigWP Meetup in New York.

Pro Tip: When heading to a #WordCamp, check local #Meetups happening at the same time.

PostStatus Publish

The Publish is a members-only conference for PostStatus members that is a more targeted format than a WordCamp. Put simply, whereas WordCamps are in large parts targeting end-users, Publish targets makers and owners.

There were a lot of very interesting sessions, with topics you would not find at a typical WordCamp. I really do think that WordCamps might be a bit too broad in scope when you're looking for business value. While not targeting any specific market segment makes them a very inclusive event, it also means that they are not optimized for any of them either, putting the pressure on the attendees to make the experience have a meaningful ROI. So, in that sense, it was kind of a great combination to have both types of conferences in one location during the same week, as you could have the best of both worlds.

Gallery images pending media migration (attachment ids: 715,716,717).

The sessions were followed by a laid-back reception where the networking took the center stage. Given the fact that the list of attendees was already so targeted, I'm sure that more than one deal has been made during this reception.

WordCamp Session Days

During the two normal WordCamp session days, I mostly kept to the hallway track. The sessions were in large parts targeted towards end-users and the community aspect, and I was surprised by the relative lack of more technical topics.

The hallway track allowed me, just as the Publish did the day before, to finally meet a lot of folks that I had interacted with for some time now through digital means, but never met in person up to that point. Meeting in person immediately adds a new dimension to the daily interactions, so I am very glad I had this opportunity. I am grateful for all the people that I could engage with, and am looking forward to the next opportunity!

The #HallwayTrack is where it's at!

WordCamp After-Party

Dinosaurs!

WordCamp Contributor Day

The Contributor Day allowed me to meet a lot of the Core development team members I hadn't met before. My main goal was to more properly identify my own role in WordPress Core development. Although I had contributed to Core for the last two releases, I'm am still feeling that I haven't yet found the right spot to be in for my efforts to return the most value. The discussions with the Core leads have helped me explore a potential approach that might currently be the best way forward for myself, and there might be an announcement coming in the near future.

These discussions were the motivation to even make the trip in the first place, and I can happily say that I feel it was worth it, and can only confirm that WordCamp US is the place to be if you want to have access to all the key players involved with the project. It will be hard to argue against attending the next WordCamp US, so I'll probably have to permanently include this in my conference attendance planning.

Peripherals

There were lots of opportunities, during and after the scheduled events, for socializing with great food and beverages. I've been to some great locations in Philadelphia, and in this context, I would like to thank Inpsyde, Human Made, Automattic, GiveWP, Media Temple, GoDaddy and Envato for their generosity, during both official and inofficial after-parties. I most fondly remember Bing Bing Dim Sum, which combined an original interior, great dim sum and witty WordCampers into a very funny and pleasurable whole.

I'll wrap up this article by sharing some impressions from the trip... Enjoy!

Gallery images pending media migration (attachment ids: 738,739,741,742,743,745,746,747,748,749,751,752,753,754,755,756,757,758,759,760,761,762,763,765,766,767,768,769,770,771,772,773,774,775,776,777,778,779,780,781,782,783,784,785).

Project Moiety - A Hypothetical WordPress Roadmap

Fri, 18 Nov 2016 00:00:00 GMT

Recently on the PostStatus Slack team, Brin Wilson started a discussion about what it would hypothetically take for WordPress to get to be installed on 51% of all websites (it currently sits at about 27% at the time of this writing):

It is an interesting thought experiment, and a lot of interesting points were made during the discussion. Matt Mullenweg weighed in on what he would think makes WordPress the "best possible product":

Helen Hou-Sandí made an interesting observation about the two different "camps" that seemed to emerge:

Franck Frémont went ahead and wrote up a proposal for a long-term roadmap for WordPress, and challenged me to do the same from the technical perspective. So here's my take on what I would think is necessary to get WordPress to account for 51% of the web.

Target Audience

Before making change suggestions to go on our roadmap, we need to define what audience we are mainly targeting. Given the methodology that is used to measure the market share (top 10 million websites according to Alexa rankings), I don't think that targeting individual end users will amount to major changes in market share anymore.

I would rather think that big enterprise clients are the next major audience to target. Right now, WordPress is lacking a lot of important features for enterprise clients, and while they might use it here and there for a blog, it is not often used as a full-blown CMS in an enterprise setting.

The next target audience for major growth opportunity for #WordPress are enterprise clients.

That's why I suspect the enterprise segment to provide the biggest growth potential and I will target my hypothetical roadmap accordingly.

Here it is then, my proposal for a long-term WordPress roadmap...

1 - Technical Requirements

For WordPress to be able to continually grow, it needs to have tools at its disposal to keep Software Entropy in check.

Please consider the following two laws from Lehman's Laws of Software Evolution (paraphrased):

The software must be continually adapted or it becomes progressively less useful.
When the software is changed, its complexity increases.

This means that WordPress will need to deal with an ever-increasing level of complexity, and following from that, making changes to WordPress gets increasingly difficult and costly (at least in time and effort, if not financially).

#WordPress needs to have tools at its disposal to keep Software Entropy in check.

As WordPress is a procedural codebase with a lot of global state right now, most changes will need you to consider the entire code base (and thus, the entire complexity) at once. Therefore, my first priority would be to refactor the WordPress Core in a way that gets rid of that global state, and allows for complexity to be properly partitioned, so that you can deal with changes and their consequences in smaller subsets of the code without having any impact on the rest of the codebase.

This is necessary to be able to adapt to small and large requirements changes that the future might bring. What needs to be avoided at all cost is to encounter the next major web revolution without the means to meet its requirements in a timely and satisfactory way. Failing to do so might eventually lead to WordPress just becoming obsolete.

I have already written about what I think needs to be done to make WordPress ready for major changes in a previous post.

Apart from these basic technical requirements, I feel that two additional components should be provided by the WordPress Core:

Logging subsystem, available to all components. Logging is such a vital feature that it ends up being implemented by nearly every substantial plugin and custom solution. Having a centralized solution provided by Core would avoid everyone reinventing the wheel and would allow for a company to route their entire logging efforts through external logging servers.
Message Bus system, allowing to decouple processing tasks from the frontend page requests. There are cron jobs right now, but their usefulness is very limited, and they often cause all sorts of issues. Having a message bus system that can optionally be decoupled from the actual WordPress process (using something like RabbitMQ) would avoid having everything under the sun be directly coupled to the web server's page rendering process.

Both of these can easily be added through custom development right now, but having them be included within Core (at least as an interface and stub, with optional implementations installed separately) would mean they can be used across vendor boundaries. As an example, if there was a central bus system, a product like WooCommerce could create an event ProductAddedToCatalog, to trigger its own update mechanisms. This would allow third-party extensions to also listen for that Event and trigger their update mechanisms as well. Both would run independently from each other (so one can't break the other) and wouldn't be able to slow down the frontend page request (as they would run in a different process and could potentially even run on a different server).

2 - Release Strategy

WordPress lifecycle management policy should be rethought, so that there are occasional windows of opportunity where breaking changes are allowed and expected, so that there's a structured way of shedding needless way and getting rid of legacy burden.

#WordPress lifecycle management needs occasional breaking changes and LTS releases.

The policy should include a long-term release schedule, with occasional long-term support releases (LTS) and recommended migration paths from one of these to the next.

Example: node.js release schedule (click to open node.js LTS schedule page)

The benefits of such a release strategy are the following:

Backward compatibility (BC) needs only be kept up to the most recent LTS release.
BC within the version spectrum between two LTS releases can be even more strict than it currently is.
Legacy code and thus complexity can be regularly discarded.
LTS releases let enterprises integrate the software into their own long-term planning.
Maintenance / updates / migrations are foreseeable and plannable.

A proper release strategy is essential for enterprises, where less "agile" processes like 5-year-forecasts are rather the norm. They need to be able to orchestrate deployments across several different software projects in cycles that span years rather than months.

3 - Compliance

For enterprise clients, controlling compliance is not a "nice-to-have", it is a basic requirement of doing business. If WordPress intends to be usable in any mission-critical context for larger organizations, it needs robust tools and solutions for implementing and/or supporting regulatory compliance. This could imply changes like subjecting the business content to enforced data retention policies, keeping auditing logs with the content workflows or even having connectors to integrate with over-arching compliance management solutions.

For enterprise #WordPress, controlling compliance is a basic requirement of doing business.

This is a very complex subject matter, and difficult to get right at an international level (being that most regulations differ from country to country). While having integrated solutions for all compliance-related areas is a lofty goal indeed, a good first step might be to go over something like the guidelines set forth in ISO 19600 and make sure that none of these recommendations are actively obstructed by WordPress at least.

4 - Editorial Workflows

Given that WordPress claims to be a full-blown Content Management System (CMS), it is quite alarming that managing content at scale (large team with large volumes of content) is not realistically possible without a combination of plugins and SaaS enhancements. The actual "Management" of the content does not extend much beyond a simple CRUD interface.

Right now, it is not realistically possible to manage content at scale with OOTB #WordPress UI.

Large content teams need workflows, customizable states, editorial calendars, communication and collaboration tools, notifications, reports, ... In this regard, WordPress better fits the "development framework" drawer rather than the "content management system" drawer, as the management experience out of the box is far from polished.

I think this should be tackled from a UX perspective first, while completely disregarding the current technical underpinnings. When the ideal workflow has been identified, the implementation requirements for this workflow should inform the development roadmap, to make the perfect workflow "eventually" possible over a series of iterations. The important thing is that a specific goal has been decided that gives direction to all subsequent UI/UX changes. While there's lots of work being done on the editorial experience, it often seems as a series of random, disjointed spot repairs, rather than a concerted effort.

5 - Integration Interfaces

Any larger organization already has lots of mission-critical systems in place that are not easily replaced. WordPress should provide the relevant integration interfaces where it makes sense, opening up the possibility to write connectors to the other systems in a reliable and fail-safe way.

#WordPress needs clear integration points to allow reliable connectors to external systems.

Although there is already the possibility to add functionality through plugins, this often results in solutions that are arbitrarily tacked onto existing functionality, and that break when using several of these in combination.

For each of the main integration points, there should be a clearly defined interface that makes it possible to add any number of these integrations in a reliable way.

Here are some examples of such integration points:

User authentication, to provide integrated Single Sign-on, letting IT manage users from outside of WP and letting users log in via their fingerprint or other enterprise mechanisms.
File management within Media Library, so that IT can attach several externally managed media libraries and document management systems (with correct support for authorization, searching, etc...)

6 - Deployments

Right now, proper deployments of a WordPress site are only possible with huge amounts of additional efforts. Two main issues need to be solved to allow for more streamlined deployments:

Environment-specific data mustn't be stored within the content database. The content database should be completely agnostic of the current environment it is being used in.
The content within the content database must be properly versioned. Currently, given two similar copies of a WordPress content database, it is next to impossible to find out what exact changes have been done in what order.

These issues are the more common nuisances that deployment systems for WordPress have to deal with. Addressing them to allow for straight-forward and reliable deployments would also encourage the use of standardized deployment tools, instead of all the custom WordPress-specific solutions you need to use right now.

#WordPress needs standardized deployment tools instead of a random collection of custom solutions.

7 - Command-line Control

An enterprise site needs to be scriptable. The IT department does not want to click through the admin screens on a daily basis to address upcoming action items. They want to write scripts that let them control the entire infrastructure as a coherent whole (or at least give it an honest try).

The IT department wants scripts that let them control the entire infrastructure as a coherent whole.

There's already a great project called WP-CLI that allows you to control your WordPress installation through the command-line. However, it has a few inherent short-comings due to the fact that it is an external addition, not part of the WordPress Core.

Ideally, WordPress would move towards adopting a hexagonal architecture, with both user interface and command-line actions having practically the same execution paths. This opens up the opportunity for more advanced command-line antics and consolidates code between both WordPress and WP-CLI. Having the actual logical processes be decoupled from the user interface representation also makes it much easier to change said user interface in the future.

8 - Certification

Enterprise HR relies on certifications to be able to hire for minimum skill levels. We all know that this is far from ideal, but it is the only way that HR departments without technical expertise can make sure they don't hire a complete lemon.

Enterprise HR relies on certifications to be able to hire for minimum skill levels.

There needs to be a network of certification bodies that can ensure that certified developers / implementors / coaches / ... do indeed offer the minimum set of skills that their position would demand. As a bonus, these institutions could also offer "standardized" training as well.

As nice as it is to "hire for attitude" or similar approaches, your company will be in real trouble if your developers cannot write basic PHP code without copy-pasting from Google results.

While this will definitely have an impact on the current low barrier of entry of WordPress, I would assume that the enterprise much prefers having gatekeepers to avoid the most obvious abuse of trust.

9 - Recommended Partners

While the 5-minute install is nice for private end-users, most larger enterprise projects start by getting implementation/integration experts on location to support the in-house IT staff with collecting requirements first. So, they want to see a list of recommended partners from their area to know where to start and whom to contact.

Enterprise IT needs recommended partners to collaborate on large-scale projects.

It is very difficult to do this without introducing bias and unfair advantages that hurt the core philosophies of the WordPress project. This should be governed by an independent non-profit.

10 - Leadership

I've kept the most important one as the final entry. It is the one element that has a direct impact on the success of all the previous points.

For a group to make a concerted move into a specific direction, there needs to be leadership. Without leadership, movement will be distributed amongst all sorts of different directions and the result will just average out to lose its impact.

For a group to make a concerted move into a specific direction, there needs to be Leadership.

If an enterprise client wants to base its 10-year strategy on a specific offering, they need to see that the team behind that offering has a strong vision and a clear direction.

The Open Source WordPress Community should try to distil true leaders from its huge group of contributors, and encourage them to proactively shape and chase a bigger vision. While we already have several forms of "middle management" at different levels, it seems to me that the overall progress is decided by a random set of actions, rather than a concerted effort.

Okay, Where's The Source?

Unfortunately, I don't have finished source code to share this time... 😜

All of the above is mostly meant as food for thought. The way the Open Source project has grown and is currently set up certainly makes it difficult (and maybe uncalled for) to have true leadership and an overarching vision. But that is probably "the next frontier" to explore.

Please put all feedback and expressions of dismay in the comments below!

Using A Config To Write Reusable Code – Part 3

Tue, 08 Nov 2016 00:00:00 GMT

This is the third part of a series of articles. (  Part 1,  Part 2 )

So far, we've found out that we need to have a clear separation between reusable code and project-specific code, and we identified the Config file as being a promising tool to map data from one side of this separation to the other. In this third article, we'll examine what our Settings page example looks like if we do indeed make use of such a Config file.

Code Against Interfaces

First, we'll want an interface that we can code against. This is important, as we don't want all of the rest of our code to be tightly coupled to one very specific implementation of the Config mechanism. Instead, we want to only couple our code to such an interface that provides the basic methods to access the data, and easily allow better and more feature-complete Config implementations to be injected later on.

interface ConfigInterface {

   /**
    * Check whether the Config has a specific key.
    *
    * @param  string $key The key to check the existence for.
    * @return bool        Whether the specified key exists.
    */
   public function has_key( $key );

   /**
    * Get the value of a specific key.
    *
    * @param  string $key The key to get the value for.
    * @return mixed       Value of the requested key.
    */
   public function get_key( $key );

   /**
    * Get an array with all the keys.
    *
    * @return array Array of config keys.
    */
   public function get_keys();
}

This is a very basic interface and it will be flexible enough for everything we need to do in these examples.

Injecting The Config Object

The basic principle now is that each reusable class will need a Config file with the configuration data that contains the project-specific bits to be injected. Our Plugin class that is responsible for instantiating these objects will inject the matching Config into the reusable class' constructor.

Here's how that would look like for the method in our Plugin class that initializes the Settings page and registers it with WordPress:

public function init_settings_page() {
   // Load configuration for the settings page.
   $config = new Config( AS_BETTER_SETTINGS_1_DIR . 'config/settings-page.php' );

   // Initialize settings page.
   $settings_page = new SettingsPage( $config );

   // Register the settings page with WordPress.
   add_action( 'init', [ $settings_page, 'register' ] );
}

We instantiate our basic Config implementation (see it on GitHub) by telling it where to find the Config file to load, and the inject that Config into the SettingsPage class.

This is still a very naïve implementation, as we need to create a separate file for each object we want to configure, and we are still directly coupling our Plugin class to a specific Config implementation here. We'll revisit this bit of code in a later article to further refine both the way we instantiate a Config file as well as the way we decide what subset of the configuration data to use.

Okay, that was all still very easy, now comes the hard part...

Structuring Our Config Data

Our goal should be to create a reusable class that can transform a properly laid-out Config file into a collection of admin pages and subpages of arbitrary complexity. We don't want to have a separate class for each page or a separate class for each section. We want to be able to just tell our SettingsPage class: "Here, this is what I need, go build it!".

The way we can achieve this is be destructuring the hierarchy that goes into building such a Settings page and allow our class to iterate over that hierarchy, looping over multiple elements wherever it makes sense. So, let's stick with our example we had in the previous articles and build a single page with a single section with two fields. This is what our hierarchical structure will look like:

admin page
settings
 \--section
     |--field 1
     \--field 2

The admin pages and the settings are only indirectly connected to each other, as you can have any number of pages without ever using settings. This is why we have these two distinct hierarchical roots.

At each level in this hierarchy, we need to decide whether it makes sense to loop over multiple elements, or whether there's only ever one possible element at that level. And as it turns out, each level of this structure can indeed be used multiple times. We can have multiple (sub)pages, we can have multiple sets of settings, we can have multiple sections per set of settings and we can have multiple fields per section.

What we'll do in our reusable class then is to have one method per level to add a single element for that level. This then allows us to iterate over our Config file and just loop through multiple elements at the same level and pass each individual item to one of these methods.

admin page          =>  add_page()
settings            =>  add_setting()
 \--section         =>  add_section()
     |--field 1     =>  add_field()
     \--field 2       > add_field()

As the entire structure then is recursive, we can simply iterate over our entire Config and pass the entire sub-array of the current level to one of these methods.

Here's our Config file:

return [

   // Admin Pages.
   'pages'    => [
      'as-settings-better-v1' => [
         'parent_slug' => MenuPageSlug::SETTINGS,
         'page_title'  => 'as-settings-better-v1',
         'menu_title'  => 'as-settings-better-v1',
         'capability'  => 'manage_options',
         'view'        => 'views/options-page.php',
      ],
   ],

   // Settings API Settings Group.
   'settings' => [
      'assb1_settings' => [

         // Settings API Sections.
         'sections'          => [
            'assb1_settings_section' => [
               'view'   => 'views/section-description.php',

               // Settings API Fields.
               'fields' => [
                  'assb1_text_field_first_name' => [
                     'view'  => 'views/first-name-field.php',
                  ],
                  'assb1_text_field_last_name'  => [
                     'view'  => 'views/last-name-field.php',
                  ],
               ],
            ],
         ],
      ],
   ],
];

This is a simplified version of the Config file to make the structure obvious. You can also take a look at the complete Config file with comments.

I added inline comments to show where our indentation levels map to our overall Settings API hierarchy.

It should be rather obvious that assembling a Settings page through such a Config file, where we have adapted the way we submit the data to best fit the conceptual structure, is much easier than fooling around with several different WordPress functions, each of which needs a different callback to be able to complete its work.

Implementing The Settings Page

To make this all work, we will parse this Config file from within our SettingsPage class and pass all the relevant bits to the corresponding WordPress functions.

WordPress normally gets a callback for each of its Settings API functions, which is responsible for rendering the corresponding element. However, as we don't want to deal with random callbacks and markup inside of functions, we map each of these callbacks to a View using a closure.

Here's the example of a field being registered with WordPress:

protected function add_field( $data, $name, $args ) {
   // Prepare the rendering callback.
   $render_callback = function () use ( $data, $args ) {
      if ( ! array_key_exists( 'view', $data ) ) {
         return;
      }

      // Fetch $options to pass into view.
      $options = get_option( $args['setting_name'] );
      $this->render_view( $data['view'], [ 'options' => $options ] );
   };

   add_settings_field(
      $name,
      $data['title'],
      $render_callback,
      $args['page'],
      $args['section']
   );
}

The $data and $name arguments are passed in by array_walk() as part of its traversal. We've also added a third argument $args which is an associative array with additional data we need to pass around from level to level.

We then use these arguments to build a closure called $render_callback. The closure basically a) makes sure the Config has provided a view to render, b) builds the contextual data for that view and then c) renders the view from within the correct context.

Then, we call the WordPress function add_settings_field() with the closure we just built as the callback.

The developer adding a new Settings page does not need to care about all of this. The only thing that (s)he needs to add is a path to a view (or an instance of one).

Yay, Free Code!

You can browse or download the source code for this iteration of the plugin from its GitHub repository. It should contain lots of comments or hopefully descriptive method names. But if all else fails, do not hesitate to ask questions in the comments section below! This refactoring round added an entire level of abstraction, so I'm not entirely sure my attempts at explaining these changes will be satisfying.

In the next article of this series (which will be out in the coming days or months), we will completely isolate the different components we've now refactored and put them in entirely separate packages.

Structuring PHP Exceptions

Mon, 24 Oct 2016 00:00:00 GMT

I seem to constantly work on improving my habits regarding the use of exceptions. I think it is an area that I haven't yet fully explored, and it is very difficult to find anything more than very basic explanations and tutorials online. While the consensus is to use exceptions, there is very little information on how to structure and manage them in a larger codebase. The larger and more complex your projects become, the more important it is to start with a proper structure to avoid expensive refactoring later on. Your client will surely be thankful!

In large #PHP projects, start with a proper structure to avoid expensive refactoring later on.

In this article, I want to talk about the way I currently set them up and use them in PHP, in the hopes to spark some discussion on the topic and get further feedback.

Why Even Use Exceptions?

Before discussing implementation details, I think it is necessary to mention what the main benefit of exceptions is when compared to something like trigger_error.

Normal PHP errors and warnings come from the procedural world, and they provide one central mechanism to deal with these errors, a function you declare as being the error handler through the set_error_handler method. Apart from being able to set different error handlers for different levels of errors, you have no further way of controlling the point where you can deal with your errors. The error handler is somewhat outside of the context of you current execution flow, so it is very difficult to do anything meaningful to recover from the error once you've reached that point.

Exceptions, on the other hand, can be dealt with at any point in your code. And, as they escalate throughout your different layers of code, you can decide for each exception at which layer and in which context you want to deal with them. This allows you to catch and gracefully handle exceptions directly in the calling code when this makes sense, and let them bubble to the surface if not.

As an example, when your code that fetches an entry from the database throws an exception, you can handle this in a nuanced way based on the type of the exception. Did the database not return a result because that ID was not known? Maybe return a NullObject instead of throwing an error. This will let a user continue working with the system without getting fatal errors. If the connection could not be established, however, we might want to have our exception bubble up to the infrastructure layer to immediately point to a bigger issue.

Build Upon SPL Exceptions

The Standard PHP Library (SPL) provides a predefined set of exceptions that I would recommend you to build upon. These provide a generalized classification and having your own exceptions extend these makes it easier for consuming code to catch them. The consuming code can, for example, choose to catch the general group of RuntimeException, which would include standard PHP exceptions as well as your own extensions of this.

For my own components, I have a standard set of exception groupings I pull in via Composer that mirrors these SPL exceptions while adding an interface to them that is specific to my component's organization. All of my custom exceptions then extend one of these.The point of adding this additional layer of exceptions is to have one additional way of filtering what exceptions I want to catch. I found this to be needed when you work in a codebase where project code is built on a framework, and that framework is built on individual packages.

Every base exceptions in that standard set both extends one of the SPL exceptions as well as implements the BrightNucleus\Exception\ExceptionInterface interface. This then effectively gives me a way of only catching "Framework-specific" exceptions targeting from within any of my code, by targeting that interface.

Here's a quick summary of how to catch exceptions at different granularities:

Catch all exceptions catch( Exception $exception ) {}
Catch all exceptions thrown by a Bright Nucleus library catch( BrightNucleus\Exception\ExceptionInterface $exception ) {}
Catch a specific SPL exception (BrightNucleus or not) catch( LogicException $exception )
Catch a specific SPL exception thrown by a Bright Nucleus library catch( BrightNucleus\Exception\LogicException $exception ) {}

As you can see, we cover layer-specific catching as well as type-specific catching with such a structure.

Naming Conventions

My current take on this is to name the exceptions differently based on whether they represent a specific error to be acted on or a group that other exceptions should extend to further qualify.

So, as an example, consider having a piece of code that tries to load the contents of a file, and that has three different ways of failing:

The file name is not valid.
The file was not found.
The file is not readable.

I would build the following exceptions to make this semantically clear:

FileNameWasNotValid extends InvalidArgumentException
FileWasNotFound extends InvalidArgumentException
FileWasNotReadable extends RuntimeException

The groups have the Exception suffix, as their naming reflects a "group of exceptions". The specific exceptions that need to be thrown don't include that suffix, though, but rather are formed by building a past-tense sentence from the error condition that has happened.

When exceptions are named in this manner, together with the concept explained in the next sections, reading the code becomes much clearer, as you are almost reading normal sentences.

Named Constructors Encapsulate Exception Logic

Most developers tend to construct the exceptions right where it happens. This often results in methods where the exception-throwing part actually has more lines of code than the actual logic. Reading code like that is very cumbersome, as you need substantial effort to identify what the important statements are.

I recommend building named constructors for your exceptions, so that the actual operation of preparing the arguments for instantiating the exception are encapsulated within the exception code, and do not pollute your business logic more than necessary.

Use Named Constructors for your #PHP exceptions to keep your business logic clean.

As an example, let's consider this piece of code:

public function render( $view ) {

   if ( ! $this->views->has( $view ) ) {
      $message = sprintf(
         'The View "%s" does not exist.',
         json_encode( $view )
      );

      throw new ViewWasNotFound( $message );
   }

   echo $this->views->get( $view )->render();
}

As you can see, the code for dealing with the exception is more complicated than the actual logic. To remedy this, include named constructors in your exceptions, like the following:

class ViewWasNotFound extends InvalidArgumentException {

   public static function fromView( $view, $code = 0, Exception $previous = null ) {
      $message = sprintf(
         'The View "%s" does not exist.',
         json_encode( $view )
      );

      return new static( $message, $code, $previous );
   }
}

You can have multiple named constructors within the same exception, depending on what context they should be instantiated in. Basically, you'll have one named constructor for each distinct message.

Now, rewriting the previous business logic to use this named constructor makes the code much cleaner:

public function render( $view ) {

   if ( ! $this->views->has( $view ) ) {
      throw ViewWasNotFound::fromView( $view );
   }

   echo $this->views->get( $view )->render();
}

Much nicer, don't you think? Apart from the code being cleaner to read, we've also put the actual string to use as message within the Exception itself, which is easier to maintain.

Localized Exception Messages

In some instances, it might make sense to allow your exception messages to be localized through gettext. However, I would advise against doing this as a general habit, as it comes with disadvantages as well.

Localizing the exception messages makes sense for a group of exceptions that is meant to be directly used to provide feedback to the user at the front end.

Although exceptions should not generally be directly used at the front end (since they should be exceptional, by their very nature), this sometimes might make sense. In such a case, localizing your exceptions is easily done by wrapping the string within your named constructors into gettext functions.

The main disadvantage is that exceptions are often searched for through their message string, by developers/sysops in log files, and by users in search engines. Localized messages break such a search strategy. If no other identifier is provided (exception name, exception code), it is very difficult, especially for users, to find out what is going on.

Localized exception messages will make it harder for your users to 'google' for solutions.

Catching Exceptions

It sounds very obvious, but it is actually pretty difficult to do in practice: Only catch the exceptions you can directly handle within your current context.

So, if your intent is to do an operation in a fail-safe way, and return a NullObject in case something goes south, it is perfectly okay to just generally catch( Exception $exception ) {}. However, if you are trying to execute an operation that needs to be completed successfully to maintain the integrity of your system, pay close attention to only catch the exceptions that you are actually able to properly remedy. Otherwise, you might prevent a more severe exception to bubble up to the top, and effectively "hiding" an issue within your system.

In most cases, you should differentiate between logic exceptions and runtime exceptions. That's why the SPL exceptions we've seen before provide these two types as their upper-most level of distinction.

Logic exceptions are exceptions where you as a developer are currently doing something wrong. You are asking for values that cannot exist, call methods with the wrong type of argument, etc... This is stuff that needs to be dealt with immediately during development. In a perfect world, a logic exception would never make its way to the production environment.

Logic exceptions should never make their way to your production environment.

A runtime exception, however, is an error condition that you have no control over during development. A database connection getting blocked by the firewall, a file permission that is incorrect, etc... These errors are unavoidable. You can not "develop a system where the database cannot fail". What you can do is "develop a system where a failed database connection produces a nice error message and alerts the system administrators, instead of throwing a fatal error".

Your code cannot 'never fail', but it can 'only ever fail gracefully'.

This is why you should make sure to catch runtime exceptions at some layer in your system (the exact layer depends on many factors), and let logic exceptions pass through so that they throw obvious error messages for the developer.

Keep in mind that you can provide multiple catch clauses, and an exception will be compared against each of them in order as long as no match was found yet.

Central Error Handler

To not just take the web server down for the exceptions you let through (whether that was intended or not), you should provide a central error handler that catches any remaining exceptions that haven't been caught up to that point.

At the very least, you should log these exceptions and their stack trace, so that you can analyze what has happened after the fact.

I recommend using something like BooBoo to wrap your entire system into such a central error handler.

Provide Your Insights

This was a quick run-down of how I am currently using exceptions. I don't think I've properly mastered them yet, though. I welcome any feedback or insights on how you use exceptions in your projects and specific issues you're facing. So please go ahead and join the discussion in the comments!

Update 2018-07-06: Changed the signature of the named constructor to use code = 0 instead of code = null, to avoid issues with strict type-checking. Kudos to Gary Jones for the feedback!

Interface Naming Conventions

Thu, 20 Oct 2016 00:00:00 GMT

At an earlier crossing on my development journey, many moons ago, it was considered best practice to use the "Hungarian Notation" for variables. You basically prefixed every variable name with a code denoting the data type that variable contained. This resulted in variable names like strName (a string) or u32Number (a 32-bit unsigned integer).

The reason why this was considered best practice was that you were dealing with low-level languages that were pretty literal when given commands by the developer. So, if you had a 32-bit variable, 32 bits of memory were reserved to contain the contents of that variable. If you copied the contents of a different 64-bit variable into that first one, the language would just allow you to do that... writing 32 bits of information into your variable and the remaining 32 bits into whatever happened to be stored immediately behind that allocated spot in the memory. You can be sure that that often resulted in very random bugs, being anything from spectacular to completely undetected until shipped. Take a look at the list of Types of Memory Errors for a nice catalog of memory abuse options.

So, with these languages, it was pretty much necessary to be aware of the exact technical implementations of what you were dealing with, to avoid greater harm. Clean, semantic code was of low priority if it made your computer explode in regular intervals.

Rise Of The Garbage (Collector)

Nowadays, most people will agree that the benefit of doing so is gone, as we have runtime checks, garbage collectors, and whatnot. That's why Hungarian Notation is pretty much gone from modern OOP development. You will generally hear that you should code against interfaces, and not against implementations. Your code should not need to know implementation details, as that just causes unwanted coupling.

In a dynamically typed language like PHP, you are even encouraged to just ignore the type and let the PHP runtime figure it out (with varying degrees of success). So, surprisingly, trying to paint three dozen eggs with the following code will just work:

for( $egg = 1; $egg <= "12 eggs" * "3 dozen"; $egg ++) {
   echo "Painting egg number ${egg}", PHP_EOL;
}

As you can see, PHP is very "flexible" with its typing system, so there's no point in distinguishing between a 32-bit and a 64-bit unsigned integer anymore.

Code Against Interfaces, Not Implementations

One of the most important principles in software development (and one that takes years to properly assimilate) is to always "code against interfaces, not implementations", with interfaces not referring to the PHP interface language construct, but rather to the concept of "abstract API that is agnostic of any specific implementation details".

The point of this is to decouple every part of your code from the other parts of the code, as well as from any specific, short-lived implementation. For example, if your business logic is expressed entirely in terms of how it interacts with such interfaces, you can replace some or all of your infrastructural implementations without needing to change that business logic.

When you start really applying this principle consistently, you'll end up expressing most higher-level logic in terms of how it manipulates the underlying interfaces, and you only ever have interfaces be injected as dependencies.

The logical conclusion should be that this conceptual "interface" then is the most important building block for you to communicate your intent to the system.

PSR-2 Suffix To The Rescue...?

A lot of developers have trouble thinking in terms of interfaces and APIs. The mind has a natural tendency of thinking procedurally, and you'll need some time to get good at thinking at the object-oriented level.

That's why folks often end up with a number of classes that are just whatever useful first implementation they could come up with.

When the PHP-FIG introduced the PSR-2 - Coding Style Guide, they included a bylaw (which is actually not part of PSR-2) that stated that all interfaces (and this time we're talking about the actual PHP language construct) should be suffixed with the word Interface for all code that the PHP-FIG would release. This is why we have a Psr\Log\LoggerInterface instead of a Psr\Log\Logger.

This has lead many developers that were still struggling to entirely grasp the OOP paradigm to take a shortcut in their development "proficiency" and let most classes they create implement an interface of the same name, suffixed by the word Interface. This way, you can "code against an interface" without needing to think about the design of your code. Neat!

What's In A Name?

Naming a thing is a very important process. It forces you to think hard about the actual nature of the thing you want to find a name for. Also, the name brings with it an entire set of assumptions and expectations. If I name a class IconRenderer, you will probably know not to use that one to make a connection to an FTP server, even without looking up its functionality in the documentation. Similarly, if I name a class Class153A , you have no clue what that could possibly do.

Naming is an important process that forces you to think about the very nature of things.

So, the following way of naming classes and interfaces also carries a lot of semantic information:

class Thing implements ThingInterface { };

Because of the way the brain makes assumptions about the logical relation of these two based on the specificity of the words, this tells me loud and clear: "Thing is what we're after, that ThingInterface is only there to support it." - And that's where we messed with our brain!

To properly follow the above-mentioned principle and general best practices, we need to make it obvious for our brain that the interface is what counts, and the actual implementation is just some noisy detail that could easily change from one week to the other:

class CurrentThing implements Thing { };

So, please take the time to let both of these snippets sink in and consider what their "appearance" suggests. You will probably agree that the perceived importance switches positions from one example to the next.

Hungarian Class Notation

I see this as a variation of the Hungarian Notation described above. It encodes a technical implementation detail of a given entity into the domain language that we should want to have as clean and clear as possible. And, yes, the word Interface is an implementation detail, as paradox as that may sound.

To make this consistent, you would also need to have names like ThingClass or $thingVariable. It provides us with information that might be accurate, but not relevant for the consuming code.

Consider the following code:

<?php namespace Example;

use Example\Message;

class MessageRenderer {

   /**
    * @var Message
    */ property $message;

   /**
    * Initialize a Renderer instance.
    *
    * @param Message $message The message we want to render.
    */
   public function __construct( Message $message ) {
      $this->message = $message;
   }

   /**
    * Render the message.
    */
   public function render() {
      echo $this->message->toString();
   }
}

Is Message a class?

Is Message an interface?

Should we even care?

Yeah, About Naming Being Hard...

I would argue that we should get rid of that Interface suffix and use the most meaningful name for the interface, not the class. But, what will the class be named then?

If we name our interface Thing, we need a more qualified name that provides additional information about our specific implementation for the class that implements Thing. Something like GenericThing or DefaultThing does not fit that requirement. Furthermore, it might mean that we will have a situation later on where we need to provide an alternative implementation. Our DefaultThing might end up not actually being the "default thing".

Think About Your Design!

You will probably encounter three different situations:

Your current code needs multiple implementations of a same concept.
Your current code provides one implementation of a concept, but is meant to be extended by more specialized third-party code.
Your current code only needs a single implementation, and there's currently no point in extending it.

Multiple Implementations Of A Same Concept

The first one makes it pretty obvious of how to define the naming. The interface is named after the concept and the actual implementations should be named after what makes it even necessary to have different implementations in the first place. So, as an example, if you need an EmailList that can work with different mailing list service providers, like MailChimp and AWeber, the names of the classes should reflect that distinction:

interface EmailList { };

class MailChimpEmailList implements EmailList { };

class AWeberEmailList implements EmailList { };

One Implementation Open To Extensions

The second situation is less obvious. But generally, the naming should reflect the way you intend the extensions/replacements to happen.

If the one implementation you provide is useful on its own, you should still name it like you did for the first scenario.

If the implementation is only meant as a starting point so that the extensions don't need to start from scratch, you can call it something like BaseThing and should make it an abstract class.

If the implementation is just provided so that the code does not throw errors, but does not do anything useful at all, you should name it after the NullObject pattern: NullThing.

Single Implementation, No Extension Planned

This is the most interesting scenario. Most developers will agree that one of the most difficult things to deal with in software development is to correctly anticipate future requirements. In this regard, "not planning to allow extensions" does not necessarily mean that this won't ever happen or be necessary in the future.

One of the most difficult things for a developer is to anticipate future requirements.

If you're going with the PHP-FIG suffix, you'll have a ThingInterface and code that relies upon that interface. Because, introducing a ThingInterface later on while all your code is programmed against a Thing would mean major refactoring. This is probably the reason why it is considered a "brainless trend" right now to just provide an interface for everything.

However, that's where my naming recommendation provides a very nice perk: If your naming does not reflect the difference between interfaces and classes, your code doesn't need to care!

Think about it for a second!

If you don't plan for your code to be extensible, just go ahead and provide a simple class Thing {};. As that is not extended, the only places where you'll encounter it is in type-hints and doc-blocks.

And after six months, your client might need to have two different things: one that runs from the database, and one that runs from the filesystem. That's where the beauty of thoughtful naming comes in... As Thing still is the actual concept you're dealing with, you can just turn the class Thing into an interface without breaking any existing code. And all of your existing code will happily accept that new DatabaseThing implements Thing, even though you never planned for that scenario!

Conclusion

As a developer, I spend most of my time interacting with the interfaces (in the API sense) that other parts of my code provide. Naming is a hugely important factor to consider and directly influences how effective my work is and how much I enjoy it.

The names of your objects should directly stem from your domain language and provide a clean representation of it. This will result in code that often is as readable as a normal English prose. The times where we need to add cryptic symbols and abbreviations or encode technical details into our entity names are long gone, and we should be glad about that!

I would love to hear your thoughts about this! How do you go about naming your interfaces? Let me know in the comments!

On WordPress And Democracy

Thu, 15 Sep 2016 00:00:00 GMT

Before you immediately click away, I want to state that this post is not about politics! I want to talk about some of the ideological decisions of the WordPress project and their impact on development. This is about data and decisions, and about where the former is missing to inform the latter.

While I'm currently trying to get more involved in contributing to the Core component that makes up WordPress, the system I chose to work with, I feel like seeing a recurring pattern whenever there's a push for progress. The people in favour of this progress are seen as the "minority" that does not want to acknowledge what the actual "majority" wants or needs. On the other side, we have people who stand up for this "majority" and try to defend its position and generally act in its best interest.

The problem with this is that any knowledge about this "majority" is mostly just subjective opinion that can neither be verified nor refuted. So, in my eyes, this situation then boils down to one vocal group trying to question the status quo, and their arguments being actually vetoed by the opposing vocal group using a "majority" assertion that simply cannot be argued about. This is frustrating for both groups, as the first just feels ignored, and the second will need to re-discuss this topic again and again. The discussion itself will just continue endlessly or slowly fade and dissolve.

There needs to be a way to resolve such discussions with meaningful data and solid assertions.

The WordPress Philosophy

Here's an excerpt from the WordPress Philosophy:

Design for the Majority

Many end users of WordPress are non-technically minded. They don’t know what AJAX is, nor do they care about which version of PHP they are using. The average WordPress user simply wants to be able to write without problems or interruption. These are the users that we design the software for as they are ultimately the ones who are going to spend the most time using it for what it was built for.

Here's another one:

Clean, Lean, and Mean

The core of WordPress will always provide a solid array of basic features. It’s designed to be lean and fast and will always stay that way. We are constantly asked "when will X feature be built" or "why isn’t X plugin integrated into the core". The rule of thumb is that the core should provide features that 80% or more of end users will actually appreciate and use. If the next version of WordPress comes with a feature that the majority of users immediately want to turn off, or think they’ll never use, then we’ve blown it. If we stick to the 80% principle then this should never happen.

These principles seem to indicate that all design decisions are ultimately run by the user base to get a kind of "democratic" voting of what changes to implement or reject. However, the reality is far from that. End users are "belittled" and only a select group of people gets to define what the "majority" actually wants.

There's also the often referenced mission of WordPress to "democratize publishing", although this seems to originate from the WordPress.com platform (although both the wordpressfoundation.org site and several make.wordpress.org posts seem to indicate that WordPress.org has accepted this mission as well).

Of Wants And Needs

My own personal opinion is that most of the time, users (as well as voters) do not really know what is best for them. What they want is not what they need. They are easily manipulated to choose whatever option seems popular, and they don't have the necessary contextual knowledge to reason about the consequences of their voting.

Still, I do think that the current situation needs to be addressed, by:

1.) either accepting the democratic notion and introducing a way for users to be included in decision-making;

2) or accepting that there is a need for long-term vision and leadership and providing a process for discussions like the above to be reasonably concluded.

So, either we go with 1.) and we need to have data about the "majority" that is used as an argument, or we go with 2.) and the "majority" has to be dropped as an argument altogether. I would prefer someone telling me "No, we won't do this, we decided we just don't want to.", rather than coming up with a bogus assertion that just leaves the discussion unresolved. That's not a productive use of anyone's time.

To this end, I have submitted a new Trac ticket in the hopes we can discuss the merits of directly letting users impact decisions. The goal is to turn the unverifiable "majority" argument into a valid assertion backed by data.

I personally would still prefer option 2.) above, as I think it would provide more focused and effective progress, but I strongly doubt that the community can agree on this if we don't even have the tools for 1.) yet.

Now, Where Did That Come From?

The impulse to create this ticket was the result of a discussion about introducing an autoloading mechanism into WordPress Core. This is a hotly debated topic, and some of the arguments were along the lines of "People using XYZ are the minority", "This is an edge case", etc...

As I cannot directly speak on behalf of the "majority", I launched a Twitter poll to collect data:

https://twitter.com/schlessera/status/773178479953272834

Of course, when I posted this data, it was quickly dismissed as not being representative and not having a large enough sample size, and rightfully so!

However, there's currently no way I'm aware of to get better data on such topics that would be statistically conclusive. That's why I think there's something missing here.

Ideological Nonsense?

What do you say? Did I drink the wrong coffee this morning, or are there other people who feel the same way? Let me know in the comments below either way!

Two WordPremieres For Me

Tue, 06 Sep 2016 00:00:00 GMT

This weekend gave me the occasion to add two new activities to my "Done" list: It was both my first volunteering experience and my first speaker gig at a WordCamp. I'd like to collect some of my experiences here, mostly for myself to not let them fade away with time.

Volunteering

I had dragged my wife Carole along to WordCamp Europe in Vienna this year, as the city is beautiful, and we prolonged our stay for it to be half-WordCamp, half-QualityTime. She was very anxious about it and expected to be surrounded by nerds making binary jokes and exclusively talking about source code. No matter how often I assured her that WordCamps are not just about web development, she couldn't imagine how she would fit in with the crowd she imagined to be there.

As it turns out, she actually fell in love with the community during these few days and, once we were back at home, she immediately started looking for other WordCamps to relive that "energizing and inspiring" experience. That's when we decided to apply as volunteers together. The first WordCamp that was available for us to apply as volunteers was WordCamp Frankfurt.

https://twitter.com/schlessera/status/772411090672156672

I took over some slots to manage one of the auditoriums, while my wife helped take care of the hello station. As our dog-sitter had to cancel at short notice, we even took along three additional volunteers, our dogs Jasper, Duke and Indra, who took care of the general happiness of the attendees.

Photo by Florian Ziegler

Volunteering is a sure-fire way of immediately getting to know great people investing time in doing great stuff. And, if you want to participate in such an event, but are not of the networking type, just apply as a volunteer. You won't need to go through any extra efforts to meet new people, and you will have specific tasks that give a purpose to your presence. If you still hesitate, just go for it! I promise you won't regret it.

Volunteering is a sure-fire way of getting to know great people investing time in doing great stuff.

For a detailed account (in German!) of how our dogs experienced the volunteering work, refer to their latest blog post! (In English as translated by Google)

Speaking

I had also submitted a proposal as a speaker. My session was called: "The Secret Of Writing Reusable Code", and is a more streamlined version of the series of blog posts about Config files I have been doing on this site.

I had trouble putting my thoughts into tiny slides, and couldn't think of meaningful code examples that would fit the format. I had planned on doing a lot of rehearsing to make sure I don't stumble over the language barrier, as writing a foreign language is nothing compared to speaking it fluently under pressure. In the end, I did not do any rehearsing at all due to becoming frustrated with the slide-writing process, and I just decided to wing it once I'm in front of the audience.

I did have a bit of trouble starting the talk, but once I managed to get into the flow, I think it all turned out to be easier than I had anticipated. I started to actually enjoy being able to talk about concepts I am passionate about to an interested (hopefully) audience.

Photo by Florian Ziegler

Some of the feedback I got from the (German) audience:

https://twitter.com/LMWA360/status/772432348721909762

https://twitter.com/ScreamingDev/status/772433062617579520

https://twitter.com/jolutionDE/status/772435410983288832

Slides

Here are the slides for the talk. In case you couldn't attend the session, I would recommend waiting for the WordPress.TV video to be published, though. The slides will probably not be very clear in isolation. I will update this post to link to the video as soon as it is available.

https://speakerdeck.com/schlessera/the-secret-sauce-for-writing-reusable-code

Video Recording

UPDATE: Here's the recorded video of the presentation. It seems to confirm that I really did have trouble getting into the presentation in the beginning. Oh well... maybe next time I'll manage to prepare and rehearse as well.

http://wordpress.tv/2016/09/12/alain-schlesser-the-secret-sauce-for-writing-reusable-code/

Call To Action

Yes, normally I try to end every blog post with a call to action, to get you folks out there to comment or subscribe to my updates. However, this time, my call to action is a different one:

Find the nearest upcoming WordCamp and apply as a volunteer!

Using A Config To Write Reusable Code - Part 2

Wed, 31 Aug 2016 00:00:00 GMT

This is the second part of a series of articles. (  Part 1,  Part 3 )

In the first part of this series, we've seen a simple "OOP" implementation of a SettingsPage class that adds a basic settings page to the WordPress admin backend using the Settings API. We've also seen that the simple fact of writing OOP code does not in and of itself make the code reusable.

The goal we identified is that we want to separate project-specific code from reusable code. To be able to put the reusable code into a reusable form, it mustn't contain any project-specific logic whatsoever.

Extracting The Views

A logical next step would be to extract the views out of the SettingsPage class, so that the latter only contains code related to the assembly of the settings page, while removing the code related to showing our project-specific fields and labels.

GitHub Repository:  Example Code: Settings Page - Broken Implementation v2

Our second iteration now has a very basic View class that can take a filename of a PHP view and render it when requested to do so. This way, we could add a mechanism to provide a path to custom views, and these custom views would be rendered instead of the default ones.

The settings page still works as expected, but the actual text fields and labels that are being rendered come from separate view files, not from the SettingsPage class we want to make reusable. This is an improvement over our first iteration. However, it still falls short of our primary goal:

The SettingsPage class still decides on the number and types of fields to provide.
The SettingsPage class still decides what data to store and where to store it.
The SettingsPage class still decides what menu entry to create.

These three points represent business logic that we can't easily fit within view files, so we need to find yet another method of splitting up the code. Points 1. & 2. could be solved by extracting a "Model" out of the class, analogous to the "View" we've already extracted. We seem to be on our way to completing the "MVC" ("Model-View-Controller") architectural pattern for this single reusable object...

When we consider going that route, though, we quickly realize that we'll end up writing more code creating custom models, views and controllers to make use of the "reusable" SettingsPage class than we originally needed for our first, non-reusable iteration. It seems as if, in this particular instance, the MVC pattern is not a good fit and will lead to a scenario where rewriting from scratch will be faster than reusing. Back to the drawing board then!

Back To The Drawing Board

To create a reusable SettingsPage , we don't want to create a complete architecture around it. At its most basic, we want to pass the business-specific code into the SettingsPage , and it should then combine it with the reusable code to provide what we need...

How about injecting the business-specific code through the constructor?

Conceptually, this would fit our needs. We could keep the two types of codes separate, and one type would then be injected into the other type at runtime. However, a practical implementation would quickly show that this is not a good method either. We'd have a huge list of constructor arguments, which will make it very complicated to actually use our reusable class.

class SettingsPage {

    // Probably not worth exploring this concept further...
    public function __construct(
        $field_type_1,
        $filed_name_1,
        $field_label_1,
        $field_description_1,
        // ...
    ) {
        // Store the huge number of constructor arguments.
    }
}

Well, how about injecting an associative array into the constructor then?

This would indeed alleviate the problem of the growing argument list, and is something that is often used in procedural code bases like WordPress (see the hundred-and-one uses of the $args argument). The associative array can be injected through the constructor and stored as a property that will then be available for the rest of the code to consult.

class SettingsPage {

    /**
     * @var array
     */
    protected $args;

    /**
     * @param array $args Associative array of arguments.
     */
    public function __construct( array $args = [] ) {
        $this->args = $args;
    }
}

This associative array can contain labels, option names, section descriptions, etc... Also, as it can be multi-dimensional, we could provide an arbitrary number of fields or sections, and the reusable code could then adapt to the actual number the array provided.

However, using such an array is not without issues:

If we type-hint against an array, we can't pass in an object implementing ArrayAccess .
If we don't type-hint against an array, we have no sanity check whatsoever.
There's no convention on how to assemble the array.
We cannot "extend" an array to provide validation and/or convenience functionality.
We cannot easily inject an array through an auto-wiring injector.
We cannot inject additional functionality into the array itself (like injecting a logger to log changes).

These issues are all more or less related to the fact that we are not injecting a real object here.

So, in essence, we'd need something like an associative array, but as a real object, right?

Yes! Such an object would be injectable trough the reusable class' constructor, and offer all the benefits of an associative array, while getting rid of the aforementioned issues that come with a pure array. Such an object is commonly called a Config file/object/class. In case this should not be obvious, this is the short form for Configuration, and it is called this way because it allows you to configure the parts of the reusable code that are not fixed. The fixed parts are hard-coded because there's no "business-specific" decision to be made about their implementation.

class SettingsPage {

    /**
     * @var ConfigInterface
     */
    protected $config;

    /**
     * @param ConfigInterface $config Configuration object.
     */
    public function __construct( ConfigInterface $config ) {
        $this->config = $config;
    }
}

When we inject such a Config object, the Config object itself can contain all sorts of logic, like for example providing means to validate its contents. Also, we can provide an extended, more specialized Config object whenever there's a need for additional functionality.

We Are On The Right Track

The Config object seems to unite the advantages of an associative array with all the benefits of a real OOP approach. We'll examine such a Config object in detail in part 3 of this series. In the mean time, feel free to share your thoughts in the comments!

This is the second part of a series of articles. (  Part 1,  Part 3 )

Simple Examples For Complex Concepts?

Wed, 31 Aug 2016 00:00:00 GMT

I'm currently in the process of preparing a talk for WordCamp Frankfurt (#WCFRA) about a concept that enables you to make large parts of your code truly reusable. I'm talking about the "store in a separate package and pull in via Composer" type of reusability, not the "copy-paste and edit" one.

However, I'm having real difficulty putting this concept into slides. Where I would have a large unit-tested class that can be reused as is and save hours of work in every future project, I end up with very complicated and over-engineered ways of greeting the world. It seems that some concepts that are useful and necessary in a given context (in regards to scope, scale and complexity) are rendered meaningless when applied to a different context.

I currently face this dilemma in several areas of my work. I am very passionate about software architecture and want to try to distil my findings into easily digestible pieces of content. But how do you sell benefits when your potential customers haven't faced the problems yet? That is a very fundamental problem when trying to share "best practices".

How do you sell benefits when your potential customers haven't faced the problems yet?

How do you show the benefits at scale when there is no scale?
How do you demonstrate the necessity to divide-and-conquer complexity without having complexity?
How do you explain the testing you can save when all you have is a `printf()`?

I'll probably manage to put together a decent slide deck for the coming presentation, but I am not entirely sure that I will be able to get my main points across. The slides will be available soon after the talk, so I'll let others be the judge...

Have you faced a similar dilemma lately? Let me know in the comments!

Using A Config To Write Reusable Code

Mon, 08 Aug 2016 00:00:00 GMT

This is the first part of a series of articles. (  Part 2,  Part 3 )

Object orientation lures you with the promise of making code reusable, letting you write source code once and then reusing it over and over in all of your projects. However, if you start delving into OOP territory, you'll probably notice rather soon that wrapping code in classes does not in and of itself make the code reusable. There are several things you need to take into consideration to produce truly project-independent objects.

One of the issues you're facing is that you'll often end up with classes that contain a wild mixture of boilerplate code, that just takes care of the necessary plumbing, actual application logic that takes care of whatever you are trying to achieve, and also "business logic", that guides the technical concerns into whatever direction that is needed to address the actual business needs.

Your goal should not be to make the entirety of this mess reusable, but rather only the subset of boilerplate code and application logic. The business logic is per definition tied to a specific business need, so it cannot be reusable across different projects and clients.

Throughout this article series, we will use a basic settings page containing two text fields as an example to try different approaches. The settings page itself does not do anything meaningful, it only serves as an example.

A broken example

Let's go through an example of a naïve OOP implementation of a settings page using the WordPress Settings API to see what the actual problem is.

GitHub Repository:  Example Code: Settings Page - Broken Implementation v1

This is a first try at implementing our basic Settings page. It uses a SettingsPage class that does all the work of setting up the page. This is proper OOP, right?

No, not really. It is more or less procedural code wrapped in a class syntax.

Let's dig deeper into the code to see what the issue is.

As you can see in the code linked above, we have a class that uses the WordPress Settings API to implement a settings page with 2 sections and a total of 4 settings. This class gets instantiated in lines 39-44 of the src/Plugin.php file and hooked up to the WordPress life-cycle.

public function init_settings_page() {
    // Initialize settings page.
    $settings_page = new SettingsPage();
    // Register dependencies.
    add_action( 'init', [ $settings_page, 'register' ] );
}

As we have a class that manages our settings, can we already reuse this code in a different project?

No, not really. It is true that we can reuse this class in a different project, but it will always take care of the exact same business needs. In this particular case, we can only reuse this class in a different project if we want to have a "as-settings-broken-v1" options page with the title "Broken Settings v1 Settings Page", and which collects the first and last names to store them within the assb1_settings option...

As an example, let's examine the method SettingsPage::options_page() (lines 114-128 of the file src/SettingsPage.php).

public function options_page() {
    ?>

<form action='options.php' method='post'>

<h2>Broken Settings v1 Settings Page</h2>

        <?php settings_fields( 'pluginPage' ); do_settings_sections( 'pluginPage' ); submit_button(); ?>

    </form>

    <?php
}

Almost any options page built through the Settings API will have a form to be posted, that includes a heading, the registered settings sections and fields, as well as a submit button. However, the actual text of the heading will vary from project to project, as will the identifier of the fields and sections to render.

Although our class is "technically" reusable, it is so limited in scope and flexibility that it will only ever be useful for reuse in the exact same project. This should make it obvious that OOP syntax in and of itself does not provide reusable code.

Object-oriented syntax in and of itself does not make your code reusable.

Different Types Of Logic

We can't easily reuse any of our source code from the example linked to above because we have wildly mixed both boilerplate code and business- or project-specific logic.

If we take a more detailed look at the class we wrote for the SettingsPage (the file src/SettingsPage.php), and try to find out for each specific statement and element, whether it is reusable, or project-specific, we can quickly see that there's no clear separation between these at all.

Any piece of code that contains project-specific data or logic is per definition not reusable across projects. What's more, if we want to reuse code without copy-pasting, this means we need to be able to separate reusable and project-specific at the granularity level that is dictated by the way we pull in this code. This being a PHP example, we would most likely want to pull in this code via Composer, making our granularity level match a Composer package. If we intended to make a reusable "Settings Page" Composer package, the entire package must be completely devoid of project-specific data or logic.

It becomes imperative then, that we have a very clear separation between reusable and non-reusable code, and we need to design our code so that these two types of logic are not intermingled.

Design your code so that the reusable parts and the project-specific parts never intermingle.

Once we've managed to fulfil this requirement, it is very easy to split out the reusable part of the code into a separate package, and, provided we've done everything right, the project-specific part of the code will not even need to be changed to work with an external package instead of the included reusable part.

How To Achieve This Separation

In the next part of this series, we will try to think of the possible ways of achieving this separation of reusable and project-specific code, and examine the concept of Config files more closely.

As always, any feedback or questions are more than welcome! Just head over to the comments section and type away!

This is the first part of a series of articles. (  Part 2,  Part 3 )

Bust That Cache Through A Content Hash

Sun, 10 Jul 2016 00:00:00 GMT

During a recent discussion with fellow developers, we talked about how to get around caching issues with static assets and shared our approaches.

Every web developer knows the issue. You want to have your static assets be cached by the visitor's browser with a very long expiry date. This accelerates the site on the visitor's site, reduces the strain and bandwidth usage on your server, and gives you good PageSpeed scores ( = much SEO! ).

However, when you start making changes to your site, you have to force a hard refresh in your browser (or even worse, reset your static caching subsystem) to get your browser to actually download that changed version of the asset.

That's why you want to include a "cache busting" system, that suggests to the browser that, when you made a change in your static asset, that new file is actually different and should not be retrieved from the cache, but freshly downloaded.

There are different approaches to achieve this, and I'll briefly touch upon the most common one before describing the method I use on my sites.

Using Query Strings

The most common approach within the WordPress sphere is to add a query string with the version or with the file modification time to the URL of the asset in question. Using the version in a query string is also what WordPress does out of the box to help you get around caches.

Default WordPress behaviour is to append the version as a query string.

The problem with this approach is that depending on what servers the visitor's connection is passing through, the assets will not be cached at all. The query string appended to the end of the URL makes some proxy servers assume that the content of that file is dynamic in nature, and dependent on the current value of the query string.

An example of why this is a reasonable assumption is the case of your search box. If the visitor enters something into that box and submits this search query, the URL will have a query string with the actual search terms appended to it: https://example.com/?s=my+search+terms . You would not want to have one cached search result page be shared amongst all your visitor's, right?

This is also the reason why some page speed analysis tools will flag your assets if they contain such a query string.

Both of the information bits suggested as values within the query string above also come with their specific disadvantages as well.

Using the version string means that you'll have to remember to manually bump the version every time you make a change. This is boring and error-prone work, and will probably lead to instances where you forgot to bump the version.

Using the file modification time seems to avoid this, but comes with a different disadvantage. If you are using a task runner with an automated build pipeline, chances are that your asset will get completely rebuilt each time your task runner launches a new build. This means that all of your file modification times will change with every single change, even if that change did not change any of the assets at all. This is wasteful, as the caches get invalidated much more often than is needed.

Also, using the file modification time means that every page request will make a file access on every static asset to collect these modification times. While these accesses are probably cached by the underlying filesystem, it might nevertheless have a negative performance impact.

A Better Approach

To improve upon the commonly used methods, the requirements are:

No query strings, only a static URL.
Cache is only busted if this is actually needed.

To meet the first requirement, we put whatever information we need to bust the cache inside of the filename itself. Easy, right?

Well, turns out, this is not that easy at all. Having a changing component within the filename makes it actually much more difficult to determine one of the data elements you need to generate the enqueueing URL: ...the exact filename!

This is why we will need some kind of mapping information that lets us deduce the current dynamically generated filename from a static filename or identifier.

To meet the second requirement, we make the information we use to bust the cache depend on the actual contents of the file. So, even if the file gets rebuilt through our task runner, it will not cause a cache bust until there was an actual change for that specific file.

The usual way of achieving this is to generate a hash of the file contents. For files with the same content, the generated hash will always be the same.

My Current Implementation

My static assets are run through a gulp pipeline. gulp is a task runner, and it allows me to automate my entire build process. It can also watch my files, and relaunch the build process every time I save a change to one of the watched files.

JavaScript files, for example, are all split up into individual modules. They are run through browserify, where all the modules are concatenated, all dependencies pulled in, and everything is optimized and minimized. This results in one single JavaScript file that needs to be enqueued at the frontend.

At the end of the gulp tasks for each of the static asset types, they are run through gulp-rev (https://github.com/sindresorhus/gulp-rev). gulp-rev reads the content and builds a 10-char hash out of it, and appends this to the filename: unicorn.css → unicorn-d41d8cd98f.css.

It will also create a rev-manifest.json file, that contains the mappings from the original name to the cache-busting name.

I reconsolidate the rev-manifest.json files from each of the asset type pipelines and save this file into the root of my assets folder.

Here's a real example of what such a rev-manifest.json file will look like (in use on one of my sites):

{
  "js/core.js": "js/core-7ab954de.js",
  "styles/atomic-editor.css": "styles/atomic-editor-ff7ef446.min.css",
  "styles/atomic.css": "styles/atomic-8f3b28e1.min.css",
  "js/frontend.js": "js/frontend-ad0cbc15.js",
  "js/backend.js": "js/backend-9b0842cd.js",
  "images/apple-touch-icon-114x114.png": "images/apple-touch-icon-114x114-13efabdd.png",
  "images/apple-touch-icon-120x120.png": "images/apple-touch-icon-120x120-bc7f8566.png",
  "images/apple-touch-icon-144x144.png": "images/apple-touch-icon-144x144-97485e89.png",
  "images/apple-touch-icon-152x152.png": "images/apple-touch-icon-152x152-98ce2b7e.png",
  "images/apple-touch-icon-180x180.png": "images/apple-touch-icon-180x180-0bab6263.png",
  "images/apple-touch-icon-57x57.png": "images/apple-touch-icon-57x57-52911982.png",
  "images/apple-touch-icon-60x60.png": "images/apple-touch-icon-60x60-ed03722d.png",
  "images/apple-touch-icon-72x72.png": "images/apple-touch-icon-72x72-a6a33372.png",
  "images/apple-touch-icon-76x76.png": "images/apple-touch-icon-76x76-8d957963.png",
  "images/apple-touch-icon-precomposed.png": "images/apple-touch-icon-precomposed-8425b83a.png",
  "images/apple-touch-icon.png": "images/apple-touch-icon-a647c234.png",
  "images/favicon-160x160.png": "images/favicon-160x160-8a1a5695.png",
  "images/favicon-16x16.png": "images/favicon-16x16-b2e8ef41.png",
  "images/favicon-192x192.png": "images/favicon-192x192-d09408e5.png",
  "images/favicon-32x32.png": "images/favicon-32x32-44ee3da6.png",
  "images/favicon-96x96.png": "images/favicon-96x96-d35b3d6e.png",
  "images/mstile-144x144.png": "images/mstile-144x144-3da555ec.png",
  "images/mstile-150x150.png": "images/mstile-150x150-5a8bfc6f.png",
  "images/mstile-310x150.png": "images/mstile-310x150-93c9b526.png",
  "images/mstile-310x310.png": "images/mstile-310x310-42ed38f1.png",
  "images/mstile-70x70.png": "images/mstile-70x70-121de451.png",
  "images/frontpage-hero.svg": "images/frontpage-hero-b25d5717.svg",
  "images/frontpage-service-01.svg": "images/frontpage-service-01-02fc2962.svg",
  "images/frontpage-service-02.svg": "images/frontpage-service-02-3a9f4bd1.svg",
  "images/frontpage-service-03.svg": "images/frontpage-service-03-49e4e765.svg",
  "images/logo.svg": "images/logo-bb31c16a.svg",
  "images/favicon.ico": "images/favicon-31234638.ico"
}

In my PHP backend code, I have a function that lets me retrieve the cache-busting name from the standard name. It is basically just a lookup retrieved from the above mappings file.

Here's what such a function looks like:

/**
 * Get cache-busting hashed filename from rev-manifest.json.
 *
 * @param  string $filename Original name of the file.
 * @return string Current cache-busting hashed name of the file.
 */
function get_asset_path( $filename ) {

	// Cache the decoded manifest so that we only read it in once.
	static $manifest = null;
	if ( null === $manifest ) {
		$manifest_path = get_stylesheet_directory() . '/assets/rev-manifest.json';
		$manifest = file_exists( $manifest_path )
			? json_decode( file_get_contents( $manifest_path ), true )
			: [];
	}

	// If the manifest contains the requested file, return the hashed name.
	if ( array_key_exists( $filename, $manifest ) ) {
		return '/assets/' . $manifest[ $filename ];
	}

	// Assume the file has not been hashed when it was not foun within the
	// manifest.
	return $filename;
}

This allows me to just refer to the normal filename without the hash within my source code. As an example, here's how to enqueue the frontend scripts:

wp_enqueue_script(
	'corescripts',
	get_stylesheet_directory_uri() . get_asset_path( 'js/core.js' ),
	array( 'jquery' ),
	null,
	true
);

Using This Approach With Browser Injection

I want to note that it is not possible to combine a cache-busting approach that changes the filename with a live-reloading mechanism that uses browser injection (like browsersync ). Due to the nature of how browser injection works, it needs the file names to remain unchanged.

So, you might want to plan on adding an option in your build pipeline to deactivate the cache busting during development time, so that you can have fast live reloads when working on your stylesheets.

Conclusion

The above approach might be a bit more difficult to set up than going with the default WordPress behavior, but it provides obvious benefits. For sites where the right caching mechanisms become critical, a pipeline like the above should be considered a requirement.

What about you, dear( $reader );? Do you use an approach that differs from the ones I mentioned above? I'd love to know about it!

Including A Constructor In Your Interface

Wed, 06 Jul 2016 00:00:00 GMT

Today, while looking through a pull request containing PHP code, I stumbled over an issue that is mostly non-existent in other languages, so it might be difficult to find reliable information on best practices regarding this specific topic. I was, of course, delighted to see that the code in question included an interface and its related standard implementation, instead of a simple class. However, the interface included a constructor as well.

When you try to find out whether you should include a constructor within interfaces, you'll probably end up realizing that this is not even possible in most other languages. PHP is very permissive in what it allows you to put into interfaces, sometimes to the point of making you consider choices you should not even be able to consider, to begin with.

So, while you might already have guessed from that last statement that I'm opposed to the idea of having constructors in an interface, even though PHP might allow it, I want to try to explain the reasoning behind my stance.

Contract About Interaction Between Objects

Object-oriented programming is about objects, and how they communicate with each other. An interface is a contract that fixes the details about how specific objects want to be interacted with. Through the interface, an object lets you know what vocabulary it understands. So, whoever the other party is, as long as it uses the correct vocabulary, it is welcome!

I'd like to quote a very important passage by Alan Kay from a mailing list discussion he had after being disappointed in what people generally perceived to be the most important point of object-oriented programming:

Just a gentle reminder that I took some pains at the last OOPSLA to try to remind everyone that Smalltalk is not only NOT its syntax or the class library, it is not even about classes. I'm sorry that I long ago coined the term "objects" for this topic because it gets many people to focus on the lesser idea.

The big idea is "messaging" -- that is what the kernal of Smalltalk/Squeak is all about [...]. The Japanese have a small word -- ma -- for "that which is in between" -- perhaps the nearest English equivalent is "interstitial". The key in making great and growable systems is much more to design how its modules communicate rather than what their internal properties and behaviors should be.

So, the interface does only and exclusively care about the interaction points between objects. The instantiation (which is the constructor's responsibility) is not about how objects interact, but rather about how to turn a class (blueprint) into an object in the first place. At the point where the constructor comes into play, you don't even have an object yet.

Devoid Of Implementation Details

The constructor is used to put an object into an initialized state when it is instantiated. The current state of an object, and whether it is considered valid or not, is an implementation detail, and should therefore not be relevant for the interface.

The internal properties that define the state of an object should be inaccessible to outside objects. As the constructor should only deal with these internal properties, all of its work should therefore also be hidden from external objects as well.

If you get passed a View object, and you want to render that view, you should not need to know whether that specific object had also asked for a Logger when being instantiated.

As Lean As Possible

The Interface Segregation Principle (ISP), which is the I in SOLID, states that an interface should only contain the methods needed for one specific role. So, as an (extremely simplified) example, when creating an interface for a Validator object, the interface probably should only contain the single method validate() .

If the interface contains too many methods, this probably points to a design issue where your interface just mirrors your classes. This might lead to code where different responsibilities are so tightly coupled that you can't make changes to one without affecting the other.

Consider Dependency Injection

When using dependency injection (and you really should), you usually pass in the dependencies of your object to be instantiated through its constructor. So, as an example, your console command might have an Input dependency and an Output dependency, so that it can receive input, parse it, and echo the corresponding output. This will yield a constructor along the lines of:

public function __construct(Input $input, Output $output);

Now, what if you now want to add logging to all of your console commands? You'll need an additional dependency on a Logger as well. This will change your constructor, though. To keep the option of replacing one implementation with another one, you need to be able to adapt the constructor so that it can accept whatever dependencies you will need. And adapting the constructor should not break your existing code.

Consider Multiple Implements

If you do have your interfaces properly segregated, like described above, you might want to have a class that implements several interfaces at once. As an example, you might want to have something like this:

class CachedRenderer implements Cacheable, Renderable { }

In such a case, if both interfaces would include a constructor, they would dictate incompatible signatures for your class. You would not be able to write a constructor that would work with both, except in the rare case where their constructor is identical.

Instantiation Needs Implementations Details

The goal of using interfaces is to make your code agnostic of specific implementations. Whenever you want to call a method declared in an interface, you can just rely on the object implementing the interface to accept that method call.

Instantiation is different, though. You cannot instantiate a new object without knowing some implementation details about the specific class to use. At some point, whether it is directly in one of your classes or factories, or whether it is within an IoC container, you will need to write a statement along the lines of:

$object = new \ExactNamespace\ExactClassToInstantiate(
    $arguments,
    $thatThe,
    $exactClass,
    $needs
);

It is just not possible to instantiate a new object without knowing details about the implementation. That's why the instantiation is usually put within factories and/or DI containers, you want to have one single place to make changes if you want to replace classes.

What About The Liskov Substitution Principle?

The Liskov Substitution Principle (LSP), which is the L in SOLID, states that wherever an object is used, you should be able to replace it with a subtype of that object without breaking the code. This means that your new object should be able to do everything that the original object could do or more.

So, what about the example we've given above where the subtype has a different constructor signature than the interface it implements. Won't this break the LSP?

The LSP is not even concerned with instantiation at all. It does not state that you should be able to instantiate all classes in the same way. It only states that, when an object of a class is being used somewhere, it should be substitutable for an object of a subclass. Note the term "object" - we're already dealing with instantiated objects at this point. The LSP is still intact, even if we have different constructors for different implementations.

What If I Want To Enforce A Specific Signature?

If you absolutely must provide a specific signature to be used as part of your API, you are already defining one part of the specific implementation, not just the contract.

In such a case, you should probably use an abstract class. Within the abstract class, you can provide as much implementation details as wanted or needed, while also marking up the parts that the extending class will need to take care of. So, you have a kind of implementation spectrum you can position your code on:

Interface => no implementation specifics provided
Abstract Class => some implementation specifics provided
Class => all implementation specifics provided

Conclusion

Don't put constructors into your interface definitions. They don't serve a valid purpose, and they might cause all sorts of issues down the road.

Did I miss something obvious? Let me know in the comments below!

OOP-NOOB Series - That Which Cannot Be Named

Mon, 20 Jun 2016 00:00:00 GMT

This article is part of the OOP-NOOB Series.

What Are We Talking About Here?

Real namespaces were only introduced in PHP 5.3, so it is quite normal to see what is called "poor man's namespacing" in codebases that were started before PHP 5.3, or that try to still support PHP versions older than that.

How Is It Being Used?

When no real namespace is being used, all the functions that are defined within a PHP script execution lifecycle share a common global namespace. Each name within that global namespace can only be defined once. When a name is already taken, PHP will throw a fatal error when defining it again. This is referred to as a namespace collision (or naming collision).

// ---[ File: as_silly_example_conflicting_syntax.php ]---

// Constant risking a naming collision.
const KEY = 'answer';

// Global variable risking a naming collision.
$data = [
    KEY => 42,
];

// Function declaration risking a naming collision.
function get_data( $key ) {
    global $data;
    return $data[ $key ];
}

// ---[ File: use_as_silly_example_conflicting_syntax.php ]---

// Output will (probably not) be "answer is 42".
echo KEY . ' is ' . get_data( KEY );

When PHP did not yet have any namespaces, people (those who cared) generally used prefixes in front of everything that was to be defined within the global namespace (functions & global variables/constants). So, instead of risking that anyone else might also try to define the function get_data(), they prefixed it with a vendor/author and/or project prefix, like as_silly_example_get_data(). This greatly reduces the potential for collisions. However, it can quickly make the code unwieldy, as identifiers tend to get really long, while still not conveying any additional meaning.

// ---[ File: as_silly_example_prefix_syntax.php ]---

// Prefixed constant.
const AS_SILLY_EXAMPLE_KEY = 'answer';

// Prefixed global variable.
$as_silly_example_data = [
	AS_SILLY_EXAMPLE_KEY => 42,
];

// Prefixed function declaration.
function as_silly_example_get_data( $key ) {
	global $as_silly_example_data;
	return $as_silly_example_data[ $key ];
}

// ---[ File: use_as_silly_example_prefix_syntax.php ]---

// Output will (more reliably) be "answer is 42".
echo AS_SILLY_EXAMPLE_KEY
     . ' is '
     . as_silly_example_get_data( AS_SILLY_EXAMPLE_KEY );

This is where the poor man's namespace comes into play! It wraps the entire code into one single class, which serves as a pseudo-namespace. Within that class, you can name your identifiers whatever you want, as long as the class name itself is safe from collisions.

// ---[ File: as_silly_example_class_syntax.php ]---

class AS_Silly_Example
{

    // Class-internal constant.
    const KEY = 'answer';

    // Class-internal variable.
    public $data = [
        self::KEY => 42
    ];

    // Class-internal function (= method) declaration.
    public function get_data($key)
    {
        return $this->data[$key];
    }

}

// ---[ File: use_as_silly_example_class_syntax.php ]---

// Output will (still) be "answer is 42".
$example = new AS_Silly_Example();

echo AS_Silly_Example::KEY
    . ' is '
    . $example->get_data( AS_Silly_Example::KEY );

So, with this version of the code, you can see that everything that is being referenced within the class is nice and short.

What's The Problem?

Now, when you extend the code above, every new function goes into your class (which makes it a method, btw). Your class will grow and grow, and you are relieved to know that you will never have to worry about a naming collision. All swell, right?

The main issue is that you might think that you're using object-oriented programming (OOP) principles. After all, you have a class construct, and you're calling methods instead of functions... This is missing the point of what OOP is, though. OOP is not about syntax. Calling something a class does not make it OOP-y.

Wrapping a class around procedural code is not OOP. Still procedural, with different syntax.

I will probably write a more elaborate article about what the main difference is between procedural programming and object-oriented programming at some point. There are lots of concepts that go hand in hand to make up the actual value that OOP provides. One of the more important ones is that it lets you split complexity in such a way that you can deal with only one part of the complexity without needing to bother about the rest. When you have a huge file with procedural code, wrapping that code in a class { } does not help you in any way to better deal with the inherent complexity of that code.

OOP lets you divide the overall complexity into smaller parts that you can deal with one at a time.

You can, of course, split up procedural code as well. However, whenever you want to make a change to one part of it, you need to consider the effect on the entire rest of your code.

What OOP brings to the table (and we're talking about a concept here, not a specific syntax) is contracts. If you divide your code, a contract between these two separate parts sets up the requirements they need to fulfill. If that contract is properly set up, both parties can independently make changes without considering the other, for as long as they adhere to the terms of the contract.

These contracts are one of the key concepts, and key benefits, that an OOP approach can provide.

Better Practice

What we have above in our last example is:

procedural code
...where we need to deal with the entire complexity at once
...where we add additional unnecessary complexity by (ab)using class syntax

If you really need to stay compatible with PHP 5.2 (and I don't recommend you do), then you can either go with the prefixed code or with the poor man's namespacing technique, knowing that this is not OOP!

If you use any PHP version greater or equal to 5.3, please, go with a real namespace instead! If you're not comfortable writing proper OOP code, avoid the class syntax, it doesn't do much by itself.

With our above example, this will produce the following code:

/ ---[ File: as_silly_example_namespace.php ]---

namespace AS_Silly_Example;

// Namespaced constant.
const KEY = 'answer';

// Variables cannot be namespaced, so this is global and needs to
// be prefixed.
$as_silly_example_data = [
	KEY => 42,
];

// Namespaced function declaration.
function get_data( $key ) {
	global $as_silly_example_data;
	return $as_silly_example_data[ $key ];
}

// ---[ File: use_as_silly_example_namespace.php ]---

// Import namespaced elements into current namespace.
// Note: Importing constants and functions only works for PHP 5.6+.
use AS_Silly_Example\KEY as the_key;
use AS_Silly_Example\get_data;

// Output will (still) be "answer is 42".
echo the_key . ' is ' . get_data( the_key );

There's a small issue with procedural code using namespaces in that you can't namespace a global variable. As you should strive to avoid global state anyway, this should not be a big deal.

However, what we gained though is that there's a clear distinction in the consuming code between locating the different dependencies (very explicit, each dependency needs to be carefully considered), and actually using them once they've been imported (very short and practical).

So, using namespaces will lead to source code where each file begins by enumerating every single of its external dependencies (external to the own namespace). This is huge, as controlling the dependencies is one of the biggest headaches in software development.

Code with namespaces enumerates every single dependency, greatly helping to control them.

Conclusion

While I doubt that this article will make you switch to using namespaces for all of your future code, I certainly hope that it helps to spread the notion that Object-Oriented Programming is not about syntax.

OOP-NOOB Series - Introduction

Thu, 16 Jun 2016 00:00:00 GMT

There's lots of articles out there that try to explain valid Object-Oriented Programming concepts in PHP. While not all of them are good or even technically correct, there's quite a volume of material that does an excellent job of showing how you can properly architect your code to adhere to commonly accepted best practices.

However, no matter how many articles are published to show you how to do things correctly, I still see horrid code on a daily basis. People trying to use the OOP paradigm in PHP, but producing code that makes it obvious they have not even grasped the most basic of concepts yet, and therefore are not getting any of the benefits of OOP.

So, as the number of "How to do X" articles doesn't seem to have much positive effect on that evolution, I decided to start a "How NOT to do X" series of articles. I call this series the "OOP-NOOB Series", which stands for "Object-Oriented Programming - No Object-Oriented Benefit", and fittingly contains the disguised word "Newb" for "Newbie" as well. It also references the term "NOOP", which stands for "No Operation" in computer science, a statement or command that just does not do anything at all.

If, for whatever reason, you feel that any of the articles in this series concerns you personally, don't be offended by its silly title. I'm just trying to be witty here. Everyone starts out as a beginner, just as I did at some point, and there's no shame in that. I'm just less of a beginner than I was a few years ago, and I want to help other people make faster progress.

Each of the articles will cover one such anti-pattern that I commonly encounter, will discuss why people might use it, what problems it causes, and how to improve upon it. I'm hopeful that this might be of value to people beginning to dabble in OOP, but who only have other people's shoddy code as an example to refer to.

If you encounter any type of code or anti-pattern which you think I should cover, just let me know in the comments here, and I'll include it in the series if applicable.

Note: The code examples in this series will all be written in PHP, but the principles discussed should be language-agnostic and universally relevant.

Articles in this series:

This list will grow over time.

That Which Cannot Be Named
The Publicity Stunt
The Rich Heritage (coming soon)
Static Antics (coming soon)
Religious Beliefs (coming soon)
Self-ignition (coming soon)
The Global Trotter (coming soon)

...

Adding A Central Autoloader To WordPress

Fri, 22 Apr 2016 00:00:00 GMT

There's a new WordPress release cycle being started right now for WordPress 4.6, and the core developers have built a wishlist to collect the feature/change requests to consider for this release.

One of the more interesting items on this list is the plan to include a central autoloader within WordPress Core (#36335 - Next generation: core autoloader proposal), which could then be reused by plugins & themes.

I recommended not building a custom autoloader for WordPress, but rather reuse the one provided with Composer. I'd do this by first implementing a very quick version to just enable the autoloader at all, and then incrementally make changes to the existing Core code to make it autoloadable. Once the Composer's composer.json schema is in place, it is very easy to add classes that are ready to be autoloaded.

I have now made a quick test to see whether that approach is viable. And my conclusion, so far, is that this is probably much easier than people think.

Basic Approach

Most of the discussions I read about adding an autoloader to WordPress make it seem like it would be necessary to do this as one big change that tries to autoload each and every file.

However, this is not necessary at all. Having an autoloader available basically just means that, if you try to access a class, an interface or a trait that has not yet been declared for PHP, it will pass the name of the missing entity to the registered autoloader(s). If they return control to PHP, and the missing entity is still not declared, PHP will throw an error. So, at any moment in time, we need to make sure that each of the PHP constructs that are being used is either known to the registered autoloader OR already loaded through a manual include/require.

The minimum viable autoloader then is an empty autoloader without any class mappings, as long as all the rest of the required classes are loaded manually.

This fact makes it possible to just load an empty autoloader to start, and then gradually make changes that combine the preparation of a class to be autoloaded with its inclusion into the autoloader's mappings, one class at a time. This lets us just start with something, and then continue to work on improving it until done.

Changing The `wp-load.php` File

The wp-load.php file is included in both the front-end and the back-end, and is responsible for providing the initial configuration of the site. This is a good place to hook our autoloader into.

<?php
/* [...] */

/** Define ABSPATH as this file's directory */
if ( ! defined( 'ABSPATH' ) ) {
	define( 'ABSPATH', dirname( __FILE__ ) . '/' );
}

error_reporting( E_CORE_ERROR | E_CORE_WARNING | E_COMPILE_ERROR | E_ERROR | E_WARNING | E_PARSE | E_USER_ERROR | E_USER_WARNING | E_RECOVERABLE_ERROR );

// Load the PHP 5.2 compatible autoloader.
if ( ! file_exists( ABSPATH . '/vendor/autoload_52.php' ) ) {
	die( 'Autoloader was not found, aborting.' );
}
require_once( ABSPATH . '/vendor/autoload_52.php' );

/* [...] */

So, before loading wp-config.php, we load our PHP 5.2 compatible autoloader.

Adding Our Classes To Composer's Autoloader

The above change makes our autoloader ready to be used, but it doesn't know anything about our classes yet.

As a simple way to get started, we just let Composer parse the entire wp-includes/ folder. It will build a classmap that maps each class name to a file within that folder. We can later have this be more nuanced if needed, but for now, this is good enough.

We also add the xrstf/composer-php52 package, which automates generating a PHP 5.2 compatible autoloader, as the default one only works with PHP 5.3.2+.

Here's what a simple composer.json would look like:

{
  "name": "wordpress/wordpress",
  "description": "WordPress is web software you can use to create a beautiful website or blog.",
  "keywords": [
    "blog",
    "cms"
  ],
  "type": "wordpress-core",
  "homepage": "http://wordpress.org/",
  "license": "GPL-2.0+",
  "authors": [
    {
      "name": "WordPress Community",
      "homepage": "http://wordpress.org/about/"
    }
  ],
  "support": {
    "issues": "http://core.trac.wordpress.org/",
    "forum": "http://wordpress.org/support/",
    "wiki": "http://codex.wordpress.org/",
    "irc": "irc://irc.freenode.net/wordpress",
    "source": "http://core.trac.wordpress.org/browser"
  },
  "require": {
    "xrstf/composer-php52": "1.*"
  },
  "scripts": {
    "post-install-cmd": [
      "xrstf\\Composer52\\Generator::onPostInstallCmd"
    ],
    "post-update-cmd": [
      "xrstf\\Composer52\\Generator::onPostInstallCmd"
    ],
    "post-autoload-dump": [
      "xrstf\\Composer52\\Generator::onPostInstallCmd"
    ]
  },
  "autoload": {
    "classmap": [
      "wp-includes/"
    ]
  }
}

Well, Yes, But...

I know what you're thinking. That's exactly zero classes right now loaded through an entire autoloader system... big deal, right?

Well, we do actually have an autoloader that is active for the entire WordPress Core. Let's try to examine what the implications are...

Doesn't Composer need PHP 5.3.2+?

Yes, it does, if you want to use it to pull in your dependencies. You do this at development time, though. So, just like most of the other development tools, this bumps requirements up. As an example, grunt, the task runner that is used, needs node.js and npm.

However, the development dependencies are different from the dependencies that the system needs at run-time on the production server. Once Composer has done its works during development, we have it generate a PHP 5.2 compatible autoloader, and this autoloader is the only thing we're using on the production server for now.

That's a huge overhead for not even loading classes through it, isn't it?

Yes, it is, and it would be a waste of resources if that was our end goal.

But we only did this to enable an autoloader that can be used by WordPress Core and all plugins & themes. Once it is available, it is easily reused all over your site, making the small overhead negligible compared to the huge benefits. What's more, the better our code base gets, the more the autoloader will turn from an overhead into a performance optimization. Less unused code will be loaded, parsed and executed, less memory allocated.

How easy is it to move a class to the autoloader?

That mostly depends on how clean the code of that class already is. Let's use an easy example to see what the general work would involve.

As an example, I want to have the _WP_Editors class be autoloaded through Composer's autoloader. To do this, we need to first find out where it is included or required. To find these, we can just search through the code, looking for the file name class-wp-editor: Search Results on GitHub.

Here's a list of code locations where that class is loaded:

/wp-includes/general-template.php (lines 2846-2847)
/wp-admin/includes/deprecated.php (lines 752-753)
/wp-admin/includes/ajax-actions.php (line 1494)

For each of these, we will remove the code that checks for the class' existence, as well as the code that loads it if necessary (meaning we just delete the lines that were highlighted in the links).

Without the autoloader we've discussed above, this will of course break our site as soon as a page request tries to load the _WP_Editors class.

However, when you examine the classmap that Composer has generated, we can see that it also includes the _WP_Editors class:

Therefore, when we try the code with our autoloader active (loaded through the wp-load.php file), we don't get an error message, the editor just pops up as expected.

So, for all well-behaving classes, we can just remove the include/require statements, and it will just work. Best of all: it will even work for plugins & themes.

Great! But what happens when we have a plugin that also includes a `composer.json` file ?

It depends on how that plugin is installed. If it is installed through one of the normal paths like the "Plugins" screen, or uploading a ZIP file, this plugin's autoloader will just coexist with the central one we've just created. It might cause conflicts if it depends on different versions of the libraries included with WordPress, but that would be bad behaviour in any case.

If however that plugin was installed by adding it as a dependency into our central composer.json, its autoloader would be combined and included within the central one. If there was a version conflict like discussed above, Composer would immediately let us know.

Ok, seems solid. But I'm sure that not all the classes in WordPress can be loaded that way!

True. But this approach allows us to see how far we can get with easy changes, and then we'll be able to draw an inventory of what needs to change to complete the autoloader project. All the while, we can already use and test the autoloader, and reap some of the benefits.

Hmm... what about the procedural code? There's files full of functions in there...

Yes. Composer provides a mechanism that lets you define a list of "files" that need to be included with the autoloader. This basically just requires every single file that you provide within that list. So, even the files containing only functions or constants can be included.

This is not useful in every case, but with a few small tweaks to the bootstrapping files, any issues can be easily overcome. And, for the overly difficult edge cases, we can still just leave the existing code in place until we find a better solution.

Conclusion

Including an autoloader within WordPress is not an all-or-nothing endeavour. With these simple changes, we have a fully functional autoloader being loaded with WordPress, and we can start refactoring the existing Core code to gradually load more and more classes (and even functions) through the autoloader.

I would love to hear your feedback about this approach, so don't hesitate to var_dump() your thoughts in my comments section below!

Adding Git Hooks Through Composer Dev-Dependencies

Mon, 28 Mar 2016 00:00:00 GMT

I have been working on refining my development workflow for some time now, in order to optimize the quality of my code. And as I am a big fan of automation, I tend to look for tools that just do their work in the background and only need my input when my mental processing power is truly needed. This leads to a greater focus on the coding and problem solving area of development.

One of the areas that was missing a satisfactory solution so far was the pre-commit checks that git was doing when new changes were committed to a repository. I had a bash script that was provided with my code, together with a small instruction in the README.md file that was explaining how to symlink that file into the .git/hooks folder. It did work, but it needed manual interaction first in order to be able to do its work.

Meet PHP Composter (or It Which Has Been Misnamed)

To improve upon this, I have written a Composer package that acts as a custom installer for Git hooks. It has the very silly name of PHP Composter, which is a word play on both "Composer" and "Post-Commit" (unfortunately, the package name PrePosterous was already taken).

You wouldn't use this package directly, though, as it will not do much. Instead, you will use packages of the type php-composter-action, that depend upon the above package to be installed and configured as Git hooks. Through a combination of custom Composer installer code, the "extra" key, and lots of intermediary files and symbolic links, this enables automatically attaching PHP methods to Git hooks.

The benefits of this approach

Code to be executed through Git hooks is correctly defined and used as a development dependency. For production deployments (using composer install --no-dev), the entire PHP Composter stuff is simply ignored, without leaving any traces.
The dependency chain is used in the correct order. Your project does not depend on an executable like PHP CodeSniffer, but rather on the one action that needs to be executed upon commit. This action then takes care of whatever stuff it needs.
The onboarding process for new developers is simplified, as they don't need to "create symlinks", "copy binaries", or whatever else is usually done. A single composer install takes care of all that is needed to start developing.
The Git hooks can be written in PHP instead of Bash, which is probably preferable for developers using Composer.
The wiring up of the Git hooks and the tools used by them is done through Composer's Autoloader, which avoids messing around with the local system's PATH settings and environment variables.
As Composer's Autoloader is used, this also means that a large project with several dozen libraries will still only pull in each dependency like PHP CodeSniffer once, instead of having small Bash scripts duplicating across all projects.
The actual actions can be centrally maintained and updated, and a simple composer update will incorporate any changes into existing packages.

If you're not interested in knowing more about the inner workings of this system, you don't need to read the rest of this blog post and should head straight to the Existing PHP Composter Actions section of PHP Composter's README file. There's only one existing action as of the time of this writing (checking PSR-2 Coding Style Guide compliance through PHP CodeSniffer), and a second one is waiting for a pull request to be merged into PHP CodeSniffer to work correctly (checking WordPress Coding Standards compliance through PHP CodeSniffer).

Technical Details

To make this work, PHP Composter will first tell Composer to use an alternative installation path for packages of type php-composter-action; instead of being installed into vendor//, they will be installed into .git/php-composter/actions/.

Then, PHP Composter will look through the package's "extra" key in composer.json to find a key named "php-composter-hooks" which contains mappings between Git hook names and PHP methods. It will then create a file .git/php-composter/config.php that collects the mappings of all such packages.

<?php
// PHP Composter configuration file.
// Do not edit, this file is generated automatically.
// Timestamp: 2016/03/28 05:03:19

return array(
    'applypatch-msg' => array(
    ),
    'pre-applypatch' => array(
    ),
    'post-applypatch' => array(
    ),
    'pre-commit' => array(
        10 => array(
            'PHPComposter\PHPComposter_PHPCS_PSR2\Sniffer::preCommit',
        ),
    ),
    'prepare-commit-msg' => array(
    ),
    'commit-msg' => array(
    ),
    'post-commit' => array(
    ),
    'pre-rebase' => array(
    ),
    'post-checkout' => array(
    ),
    'post-merge' => array(
    ),
    'post-update' => array(
    ),
    'pre-auto-gc' => array(
    ),
    'post-rewrite' => array(
    ),
    'pre-push' => array(
    ),
);

Then, it will create symbolic links from each Git hook ( .git/hooks/) to the Bash script vendor/php-composter/php-composter/bin/php-composter.

#!/bin/bash

# ------------------------------------------------------------
# Git Hooks Management through Composer.
#
# @package   PHPComposter\PHPComposter
# @author    Alain Schlesser <alain.schlesser@gmail.com>
# @license   MIT
# @link      http://www.brightnucleus.com/
# @copyright 2016 Alain Schlesser, Bright Nucleus
# ------------------------------------------------------------

# Collect environment data.
hook=`basename "$0"`
package_root=`pwd`

# Make sure we have a PHP binary.
php=`which php`
if [[ $? -ne 0 ]]; then
    printf "PHP binary could not be found. PHP Composter aborted.\n"
    exit
fi

# Verify that the bootstrap.php file exists.
if [[ ! -f $package_root/.git/php-composter/includes/bootstrap.php ]]; then
    printf "PHP Composter bootstrap file was not found. Please reinstall.\n"
    exit
fi

# Launch the engine.
$php $package_root/.git/php-composter/includes/bootstrap.php $hook $package_root

This shell script is only a small wrapper to launch the file .git/php-composter/includes/bootstrap.php (a symbolic link to vendor/php-composter/php-composter/includes/bootstrap.php), which is responsible for parsing the previously generated configuration file and calling the corresponding action.

<?php
/**
 * Git Hooks Management through Composer.
 *
 * @package   PHPComposter\PHPComposter
 * @author    Alain Schlesser <alain.schlesser@gmail.com>
 * @license   MIT
 * @link      http://www.brightnucleus.com/
 * @copyright 2016 Alain Schlesser, Bright Nucleus
 */

use PHPComposter\PHPComposter\Paths;

// Get the command-line arguments passed from the shell script.
global $argv;
$hook = $argv[1];
$root = $argv[2];

// Initialize Composer Autoloader.
if (file_exists($root . '/vendor/autoload.php')) {
    require_once $root . '/vendor/autoload.php';
}

// Read the configuration file.
$config = include Paths::getPath('git_config');

// Iterate over hook methods.
if (array_key_exists($hook, $config)) {

    $actions = $config[$hook];

    // Sort by priority.
    ksort($actions);

    // Launch each method.
    foreach ($actions as $calls) {
        foreach ($calls as $call) {

            // Make sure we could parse the call correctly.
            $array = explode('::', $call);
            if (count($array) !== 2) {
                throw new RuntimeException(
                    sprintf(
                        _('Configuration error in PHP Composter data, could not parse method "%1$s"'),
                        $call
                    )
                );
            }
            list($class, $method) = $array;

            // Instantiate a new action object and call its method.
            $object = new $class($hook, $root);
            $object->init();
            $object->$method();
            $object->shutdown();
            unset($object);
        }
    }
}

As you can see from the code above, this will get the hook name from the small Bash script that was executed, iterate over the configuration file to find the corresponding action, instantiate the action's class, and finally execute that action.

This whole "symlinking business" is done on each composer install and composer update to always keep your Git hooks current, and to avoid having stale links (for example, by removing the vendor folder), Composer is always told that the actions are not yet installed, to force a complete redeploy on each change.

This is still a very early release for PHP Composter, so I appreciate any feedback. I do think that this is very useful and I will incorporate it into all of my projects. I would be happy to hear about any other uses of PHP Composter out in the wild, so do let me know of your specific use cases!

Attracting Developers To WordPress

Sat, 19 Mar 2016 00:00:00 GMT

Ryan McCue, Senior Engineer at Human Made and WordPress Core Developer, has posted a series of tweets regarding the fact that WordPress is far from an ideal platform for developers, which has spawned a lot of discussion.

https://twitter.com/rmccue/status/710464212183572481

https://twitter.com/rmccue/status/710469646680399874

As a long-form response to this, here's a list of changes I would like to see in WordPress, and how I would try to address backward compatibility (BC) concerns. I don't pretend to know that this is the absolute best way to tackle the problem, this is purely my own biased opinion, and how I would try to fix the issues if I were in charge.

Keep in mind that I am mostly interested in having a robust, future-proof platform that is easy to maintain. Some of the changes proposed below might be a disadvantage to the end-users without a developing background. One of the major hurdles that WordPress currently faces is that it tries to focus on end-users, while actually increasing the need for developers to implement solutions. That one paradox is probably at the heart of a lot of drama in recent times.

I also want to mention that I don't list any of the more implementation-specific details, like whether there is a Separation of Concerns, whether the code is SOLID and DRY, etc... I only concentrate on the critical path from the now to a future where we can more easily get rid of cruft and improve at an accelerated pace. Once this we've enabled this, taking care of the implementation specifics should be a piece of cake (hopefully)!

1. Bump PHP Version

I know this has been talked to death already, but it is still a major obstacle. WordPress needs to bump its minimum PHP version requirement (not the recommended version). With great power comes great responsibility, and all the bragging about running one quarter of the web has a very bitter taste to it because of this.

It is completely irresponsible and totally inexcusable to run a web server on PHP version 5.2 in 2016. By keeping the requirements this low, WordPress only caters to the people not ever looking after their servers, and the web hosting companies that sell very shoddy services to unknowing customers.

This absolutely has to stop!

Any serious hosting solution will keep their PHP version as current as possible, even if only to save money on reduced resource usage. I might even go so far as to connect the word "malicious" to 5.2 hosting...

Compatibility considerations: None, that's the whole point. Drop the compatibility with any version that has no security support, preferably even versions that have no active support. ( Supported PHP Versions )

2. Use Namespaces

Developers have known for many decades now that polluting the global namespace is bad, and that it will come back to bite you. The fact that PHP was late to the party with introducing namespaces does not mean that we can continue to ignore this now.

Imagine having all of your files (your photos, your videos, your documents, your operating system's files, your applications' files, ...) be regrouped in one single folder. Bad idea, right? Everyone knows that....

So, once we've dealt with point 1. above, there's no valid reason not to use namespaces.

Compatibility considerations: To make the initial switch and provide legacy support for some time, the current functions can still stay and just redirect to the corresponding namespaced variants:

function wp_get_attachment_url( $id ) {
    \WP\Core\Attachment::get_url( $id );
}

3. Use an Autoloader

Once point 2. has been taken care of, it is very easy to integrate an autoloader into the mix. This goes hand in hand with point 4. below, as the package manager can tell the autoloader what namespaces need to be taken into account.

Compatibility considerations: None at all, autoloaders are already used all the time within WordPress plugins and themes. Combined with a proper architecture, an autoloader in WordPress Core will probably improve performance and memory consumption.

4. Use a Package Manager

Every non-trivial project reuses existing libraries and components. To avoid manual updating chores, this should be controlled and automated through a package manager, that pulls in dependencies and sub-dependencies. If this is combined with a corresponding way to define the needs of the project, the number of dependencies pulled in for WordPress Core could even be drastically reduced for most projects.

In the PHP world, the de-facto standard for package management is Composer, and I don't see any valid reason not to use this as the package manager for WordPress projects. In fact, many developers already use Composer at the site level to update their entire project with one single command, with WordPress Core just being one of the many dependencies of a WordPress project.

Compatibility considerations: None at all, provided that point 1. above has been taken care of.

5. Use Semantic Versioning

When using an automated package manager like described in point 4., it becomes hugely important to be able to control updates in an automated way, and to stop updates if they would break BC.

That's what Semantic Versioning is for. It would provide a way for automatic updates to just stop right before a BC would be introduced, and to also have security fixes that can be applied to previous, legacy versions.

This would change the WordPress BC philosophy from "we don't break BC, ever" to "we don't break BC for versions that are not meant to break BC", which, as you might have guessed, paves the way for controlled breaking of BC.

Compatibility considerations: None, this would be an easy improvement without any downside. Just start at some version and let people know what the versions mean.

6. Use Proper Object-Oriented Programming

I know that OOP is not the holy grail of development, but for a system of any non-trivial complexity, it is still heaps better than a procedural approach when it comes to maintainability and extensibility.

The procedural code is in fact one of the reasons why it is so difficult to make changes to WordPress Core without breaking BC. You can't just extend an object and simply pass the extended version down the pipeline... there is nothing to extend, and there is no pipeline (whatever that may be), the plugins and themes are directly coupled to some of the innermost implementation details.

I've seen lots of efforts in this direction already, but I have to say that most of the "classy" code in WordPress Core is still very much procedural code written in class syntax, and the whole purpose is to switch from "emulating namespaces with prefixes" to "emulating namespaces with classes", which should immediately stop in favour of point 2. above.

OOP is not about syntax, it is about having decoupled objects, that communicate with each other via contracts. Everything should be coded against interfaces, not concrete implementations. This way, the objects can be easily extended, and their implementations can be changed without breaking anything any dependent code.

So, having a WP_Post class is nice. Depending on a WP_Post class is not. The plugins and themes should instead depend on a WP\Core\Post interface, and know that, whatever object they will get, they will be able to call its get_title() or render_content() method. If WordPress Core decides to send them a WP\GitHub\MarkDownGist which implements WP\Core\Post instead, the theme should not need to care...

Compatibility considerations: As with point 1. above, the current functions, classes and methods could be kept, and would redirect to Facades, that serve the purpose of an Anti-Corruption Layer between the current code and the new OOP code. The OOP code should be built to provide an optimal model, and ignore the requirements of the legacy code. The Facade will then translate between these two. Using this approach, the new model can be built alongside the legacy one, and they can coexist as long as is necessary to get everyone migrated to the new model.

OOP Examples

Point 6. is the biggie and should be the goal for the foreseeable future. Once there are proper abstractions for all the major subsystems and models that WordPress Core uses, and provided that they are properly decoupled from each other, it becomes trivial to replace specific parts with custom implementations.

Let's take one of the suggestions people provided as an example and try to imagine how that could work in a proper OOP WordPress, so that it can be easily extended/customised.

Example - Routing

https://twitter.com/rachelbaker/status/710798022737858560

https://twitter.com/MZAWeb/status/710644905123651584

People don't seem to like the way routing is handled in WordPress. Currently, the WP Rewrite API is responsible for parsing your pretty permalinks, transforming them into a WP_Query request, and dispensing developer headaches along the way. What would a flexible, extensible routing system look like for WP?

Well, at a very basic level, we need a WP\Core\RouterInterface that accepts a Psr\Http\Message\ServerRequestInterface and chooses a matching object implementing the WP\Core\RequestHandlerInterface that can handle() that request.

We'd then have a WP\Core\RewriteAPIRouter that implements WP\Core\RouterInterface to provide the current behaviour.

If you need something more than the standard WP Rewrite API, you can either replace the WP\Core\RewriteAPIRouter with a custom implementation that implements WP\Core\RouterInterface, or you can wrap it with a Decorator.

Type Declarations using Interfaces in PHP

Mon, 14 Mar 2016 00:00:00 GMT

I've recently completed a preliminary code audit on an existing WordPress plugin, and one of the goals I've set for that audit was to decouple the code from the JavaScript library it was using, so that it could easily be extended to support future versions of that library.

A question came back about the constructor syntax I was using, and how that actually worked. I'll use the opportunity to write the answer in form of a blog post, as I think that this is a concept that might be new to a lot of WordPress developers.

Let's Automate Watching of TV Series!

To explain the concept, let's assume we are writing a wrapper plugin for the awesome (and yet to be invented) TV Series Watcher V1 JavaScript library, which can automatically watch TV series for you, while you can concentrate on your actual work.

In the plugin, I would have proposed a constructor like this for the wrapper plugin:

class WatcherPlugin {
   public function __construct( WatcherInterface $watcher ) {
      [...]
   }
}

The first thing that was new to the person asking the question is the way the argument inside of the constructor is written. Instead of just having an argument, $watcher, we have two words that are related somehow (WatcherInterface $watcher) for the first argument.

As I have worked with several programming languages in the past, this is a very common thing for me. But as it turns out, this is "rather new" and less common in PHP usage.

Having a qualifier in front of an argument name is called a "type declaration", and was only introduced with PHP 5.0 (when it was still called a "type hint"). With PHP 7.0 it was extended to be usable with scalar types too.

It tells PHP what types of arguments to accept for the function call to be valid. If you now try to call this constructor by passing it the wrong type, you'll get a PHP error right away. You might for example try to pass in a string to the constructor:

$watcher_plugin = new WatcherPlugin( 'testing' );

This will immediately trigger a fatal error (or throw a TypeError exception in PHP7). So PHP itself simply does not allow you to call the constructor with a wrong argument. You can define what the requirements for your method are, and make sure that no one can call the method without fulfilling the requirements.

What are the Benefits of Using Type Declarations?

Here are some immediate benefits, in an arbitrary order:

You don't have to check the argument before starting to process it. So, you can avoid code like this:

if ( ! $watcher instanceof WatcherInterface ) {
   return;
}

As a side-effect of the previous benefit, you'll avoid hard-to-debug code where the method gets the wrong type of argument, but somehow it fits good enough for the code to not immediately break. This can happen if the argument is not immediately used, but rather passed on to other places in your code. It might even end up being stored in your database, and only causing an error a week later when it is eventually used. You'll always want to have your errors be as close as possible (in source code as well as time) to your bugs!
It is one way of documenting what the exact requirements for your method are.

Why the Hate in PHP?

There are a few reasons why not everyone uses type declarations in PHP, and I want to quickly address these reasons.

It can have historical reasons. Before PHP5, there was no support for type declarations. PHP was built to be very "convenient" for coders, to "quickly get the job done". With the growing success of PHP, projects became bigger and more complex. And as it turns out, "convenient in the short term" is often a synonym for "comes back to bite you later on". That's why PHP5 finally addressed this issue and added type declarations. It was not immediately possible to add them for scalar types, though, and we've had to wait until PHP7 for these.
It can indicate design flaws. Some developers mention that you can have differing type declarations when overriding methods, and that they prefer to have no type declarations rather than have them cause issues. I personally have never perceived this as an obstacle, and I suspect that this points to a flaw in the architectural design of the application, rather than a technical limitation of the language. The whole point of using type declarations and interfaces is to have consistency amongst your methods and object interactions. When you go go on and mix these up, letting and extending class change the type declaration, goes against the very principle this is based upon.
It is less useful in procedural programming. No scalar types before PHP7 together with no classes/interfaces means that type declarations are much less useful in procedural programming as they are in OOP.

Using Type Declarations with Interfaces

Okay, so now we know what a type declaration is. In our example above, we combine this with the use of an interface as well. We don't tell PHP: "I need an object of type TVSeriesWatcherV1 to work correctly.", but rather: "I need some kind of object that is able to fulfil the WatcherInterface contract.". So what is this all about now?

Interfaces let you define a contract between different components, so that they can interact with each other without caring about the actual implementation of their respective partners.

The above diagram shows how such a relationship would be visualised using UML (quick PDF cheat-sheet).

The WatcherPlugin only ever interacts with the WatcherInterface, it does not know how the actual library should be implemented, or how many different versions there are. The WatcherPlugin's code is very simple as a result:

class WatcherPlugin {

   protected $watcher;

   public function construct( WatcherInterface $watcher ) {
      $this->watcher = $watcher;
   }

   public function play_episode( $episode ) {
      $this->watcher->watch( $episode );
   }
}

Note that the pattern above is a basic version of "Dependency Injection", meaning that the code itself does not go about retrieving its dependencies from all over the place, getting tightly coupled to the surrounding code in the process, but rather that it gets all of its dependencies injected through its constructor. The outside code needs to make sure that WatcherPlugin gets everything it needs. WatcherPlugin then stores the reference to this dependency inside of an internal property of its own, so that it can reuse that dependency later on.

Splitting up the Implementations

What we've also done is that we've split up the actual implementation into code that is reused by each version of the library, and code that changes between versions.

The code that remains unchanged between versions goes into an abstract class AbstractWatcher that implements WatcherInterface. This lets us add all the boilerplate code that will never change between versions of the library.

Then we have two different concrete implementations in our example, TVSeriesWatcherV1 and TVSeriesWatcherV2, and each of them extends AbstractWatcher. Using this approach, once a new version V3 comes out, we can simply add a third TVSeriesWatcherV3 that also extends AbstractWatcher and just add the small bit of code that needs to change between versions. The WatcherPlugin does not need to be changed to be able to use this new version.

So, when we combine this approach with the type declaration we've used above, we've written code that defines a very specific requirement using an interface: "WatcherPlugin needs to receive an object that it can watch()".

Another Round of Benefits

This opens the door to another set of benefits, that go far beyond what we've identified before.

When correctly used with a robust Dependency Injection Container (for example `Auryn`), or DIC, we can have the outside code tell the DIC what exact version will be used in what context, and the DIC will handle injecting the correct version into the `WatcherPlugin`'s constructor automatically at runtime.
Completely external code can even extend the `AbstractWatcher` and register this external version with our DIC. The plugin "just works" with that new external version, without ever having known about it.
We can run properly isolated unit tests with our `WatcherPlugin` by injecting a mock object that implements `WatcherInterface`. Unit tests should always be run in isolation, so that each method can be tested individually, without relying on any external context.

Phew!

This post touches a lot of advanced concepts, and some of these only make sense if you've dabbled in object-oriented programming before. I hope that I've been able to explain this in a way that it nevertheless makes some sense to most of you.

I would love to hear from you fellow PHP developers!

Do you regularly use type declarations?
Do you make extensive use of interfaces to decouple your code?
What about dependency injection?

Hit the comments hard, this surely is a topic that needs more exposure in PHP!

PHP Feature Detection Library

Thu, 14 Jan 2016 00:00:00 GMT

Link to GitHub Repository: PHPFeature

I had a short conversation on Twitter the other day with Andrey Savchenko ( @Rarst ). He was wondering whether feature-centric PHP requirements would work in WordPress extensions.

Although he was talking about the features of the "WP extensions", I asked myself why there was no feature detection library available for PHP, similar to what Modernizr does for the browser features. Traditionally, PHP requirements are always based on a version number constant.

https://twitter.com/schlessera/status/687239552147288066

Meet the PHPFeature Library

PHPFeature is a first draft of such a PHP Feature Detection Library. So, instead of checking for a specific PHP version number (which forces you to know and compare which features were introduced by which PHP versions), you can simply tell the library what features you need, and it will tell you with a simple boolean value whether these are supported or not. You can also ask the library about the absolute minimum version required to support the set of features you've requested.

Why Bother?

What is the use of such a library? Well, for one, it simplifies knowing the required version you need for your code. Instead of building an entire matrix of version numbers, to find out what effective version is the most recent required one, you simply add the feature you intend to use to he array of features that gets passed in to the library.

The features that are included in the reference list could also include more minor stuff. Although pretty much everyone knows when namespaces were added, knowing when a specific bug was fixed might be more obscure data that is harder to come by. So the features you are checking the support for might also include specific bug-fixes.

The library could also be extended to include PHP extensions and libraries. So, instead of checking for a specific PHP version or an extension or a library, you could just check for the feature, and the library would tell you whether it is supported in any of its possible forms.

How Do I Use It?

To include the library in your project, you can use Composer:

composer require brightnucleus/phpfeature

Alternatively, you can copy the classes inside of your application and make sure that your application can find them.

Usage is pretty simple, it only comes with two methods so far.

public function is_supported( $features );

This returns a boolean value telling you whether all of the features that you passed in are supported by the current PHP version.

public function get_minimum_required( $features );

This returns a SemanticVersion object that contains the minimum PHP version that supports all of the features that you passed in.

Here's an example as provided by the README.md:

<?php
/*
 * PHPFeature example usage code
 */

// Array of strings to define what features you need.
$features = array( 'namespaces', 'traits' );

// Instantiate the PHPFeature library.
// When you don't provide a version number as the first argument,
// the version of the currently used PHP interpreter is fetched.
$php = new PHPFeature();

// Check whether all of the features are supported. If not...
if ( ! $php->is_supported( $features ) ) {

    // ... throw exception and let user know the minimum needed.
    throw new RuntimeException( sprintf(
        'Your PHP interpreter does not support some features needed to run this application. Please upgrade to version %1$s or newer.',
        $php->get_minimum_required( $features )
    ) );
}

For more complex architectures, you could use this library to conditionally load certain files, or to conditionally extend classes with more advanced versions implementing the same interfaces.

Future Plans

This is more of a proof-of-concept, than a production-ready library at this stage. If there's interest in using a library like this, though, I can see it becoming a standardized way of dealing with different PHP versions in your code.

One thing I would like to change is to lower the PHP requirement of the library itself to 5.2 (currently 5.3.2) so that it can be reliably used with WordPress.

If you think that this approach might be useful in any way and want to contribute, just let me know or provide pull requests, all contributions are welcome.

You can find the complete source code on GitHub:

https://github.com/brightnucleus/phpfeature

Is WordPress a Dependency?

Fri, 18 Sep 2015 00:00:00 GMT

I am currently on a quest to find the perfect setup for my WordPress projects (who isn't, right?). I do think that a large part of what makes or breaks complex software projects is dependency management. And there are dependencies at every level of your projects, be they languages, libraries, servers, stakeholders, whatever. When someone pays you to attack a project (outside of hobbyism), he generally pays you to fulfil a business goal. And it's your task to keep the things in check upon which this business goal "depends" on.

The problems you'll deal with when trying to manage these dependencies are not new to your project; they have been the same problems for many moons. And many smart people before you have found solutions to these, which can be found somewhere on a spectrum from "satisfying" to "perfect".

You'll probably agree that it is best to learn from other people's mistakes and reuse their solutions, instead of being stubborn and insisting on making these same mistakes yourself (wasting a lot of time & money in the process).

On most levels that get touched by your project, the problem of "dependency management" has probably been solved already. For example, to be able to build a server stack that can run on any hardware, we have tools to virtualize/automate/abstract the entire hardware your stack could be dependent on.

On the "libraries" or software level, you have different package managers that you can use, depending on what platform or programming language you like to work with. For the PHP language, the package manager of choice is Composer.

When I researched ways to include WordPress into a proper dependency management system for my software layer, I stumbled upon a Core Trac ticket that had logged a debate I did not expect: whether WordPress was a dependency of a site, or whether it was the site itself. So, instead off discussing how to best pull WordPress in, the discussion veered off into a question of whether this was even a good idea in the first place.

So here's how I see it (and I still have a lot to learn, I admit, so I'm totally fine if you disagree). The point of starting a project to meet a business goal is usually to have some business logic be executed on business data. I don't want to go into any technicalities here on where the data comes from or how the logic is executed; these are details you should discuss with your local software engineer.

But the business logic is the thing you are getting paid for. Everything else is just a dependency of making this work. So, I consider even the website itself to be a dependency, as you could also have a smartphone app, or staff members, or subcontractors, or a mainframe be responsible for executing this. As I am a software engineer and web developer, I tend not to be asked to manage anything but a software solution.

Each dependency can have its share of sub-dependencies. So, if I say that my business goal is to collect a list of emails of potential customers, my main dependencies probably are a website and an email list provider. Now, the website dependency introduces a couple of new dependencies, like a domain name, a web server, etc. The web server again has sub-dependencies, like the OS it runs on, the scripting language and DB it uses, and so on.

Somewhere rather deep inside these dependencies, you have WordPress, a CMS, that provides an abstraction of the DB and the web server (and some other things, too), so that you can better concentrate on implementing your business logic, instead of dealing with the DB directly or building endless user interface elements for management users.

So, if we ignore all the levels above it, and just concentrate on the web site level ... is WordPress the site, or is it a dependency of the site? I would argue that it is pretty clear that WordPress is "just" a dependency, as you can have all sorts of stuff running alongside WordPress on your server. And the fact that there is a WP-REST API project that will be integrated into WordPress core and that allows you to have a a public-facing front-end that can be another platform or language and that is completely separate from the WordPress backend tells me that at least a portion of the WordPress core developers agree.

Although I understand the emotional attachment one might have to a project that is by your side for several years, I do think that the WordPress developers need to take a step outside of the WordPress ecosystem and exchange best practices with other platforms. Switching from [platform XYZ] to WordPress is a very frustrating experience so far, as the potential far exceeds the practical realities.

I'd love to have some feedback on this, as my conclusions might not be so "evident" as they seem to me.

Woah, hold on a sec...

Thu, 17 Sep 2015 00:00:00 GMT

Hi there, how are you doing? I hope you're comfortable... I really need you to enjoy the reading experience here on this blog, as I need you to come back from time to time.

You see, I always try to stay "professional", and "unambiguous", and all sorts of other adjectives when communicating with clients and partners. But I want to build this site into a blog where I can also communicate in a more personal way, without censoring myself. To make this work, though, I'll probably need an audience to keep me motivated. That's where you, the reader, come into play.

So, if you're okay with philosophical bouts and technical rants, paired with inadequate humour and word plays that seem witty to me only, you're very welcome! This blog will probably end up having posts about "Software Development", "Self-Employment", "Technology", "Uncategorized"! I'll even throw in a "Personal" or two.

You can probably see the area at the bottom of this post, right? This is where you can put in your complaints. Don't think my jokes are funny? Just let me know, and I'll make sure I'll perhaps consider eventual possibilities of optional change.

This post has been dragging along already, and without much substance, so I'll stop here. But I count on you to be present when I publish the next post, so don't disappoint me, dear "Reader"! ;)

See you on post #2!

Alain