Forem: Carl Alexander

What’s the difference between headless and serverless WordPress?

Carl Alexander — Thu, 14 Oct 2021 18:18:09 +0000

In the last few years, two new terms have emerged in the WordPress and larger web development space. Those two terms are headless and serverless. On top of both being terms ending in "-less", they're two terms that aren't very self-explanatory. (Are there still servers with serverless? Yes. Is headless some new horror movie category!? Nope!)

But to make things worse, because you often use these two new development paradigms together, people use the two terms interchangeably or think they’re the same thing. But they’re not! This increases the confusion and suspicion around both paradigms.

So with that in mind, this article will walk you through both concepts. This should hopefully clear some of the confusion. But we'll also see how both paradigms are changing the WordPress development landscape. Let's go!

Headless: decoupling frontend and backend

Headless WordPress websites are the result of the rise in popularity of JavaScript as a full-fledge programming language. As JavaScript popularity grew, new ways to build websites became popular. King among them was the single-page application.

If you're not familiar with a single-page application, it's basically a JavaScript application that runs in your browser. If needed, it'll communicate with a backend to get any data it needs or perform other operations such as sending email. With WordPress, that backend is your WordPress installation.

A single-page application like I described is headless. That's because the frontend (the head in the analogy) is ~~decapitated~~decoupled from the backend (the body). This separation between backend and frontend is really all that headless means.

So when we're talking about headless WordPress, it's just a WordPress site where you only use WordPress as a backend. You don't need to use a theme to display your WordPress content. That's done by the frontend application. In that scenario, your major frontend decision on the WordPress side is whether you want to use the REST API or GraphQL API to communicate.

Serverless: on-demand computing

This brings us to serverless. Serverless is a marketing term to describe function as a service. Functions as a service allow you to run code on demand without the need to manage a server. This is where the serverless name comes from.

Serverless is an interesting paradigm shift because it allows developers to focus on writing code and not worry about where it'll run. If you're curious about how hosting WordPress using serverless is different vs using a server, you should check out this article. The interest in serverless is also tied to the growing popularity of microservices architecture. With serverless, it's easy to create small microservices by just writing some code and deploying it.

Once deployed, you also don't have to worry about scaling these microservices. Serverless scales automatically. So there's no worry that you'll blow up your server if you get a traffic spike.

This ability to scale on-demand is a very powerful feature of serverless. It's also why serverless makes for an ideal platform for hosting WooCommerce. Hosting a WooCommerce site is more demanding than a regular WordPress site and serverless, with its on-demand scaling, is ideal for it.

Why are headless and serverless used together?

Now, the more interesting question is why are those two terms confused with one another. It's basically because both paradigms are complimentary. Let's go back and look at headless again.

With headless, you have a JavaScript frontend application that runs in the browser. You don't need a server to host it. You just need to put the code somewhere the browser can download it. (Often it's just on a content delivery network (CDN).)

This frontend application needs to communicate with a backend to get any data it needs, make changes to it or perform other operations. This backend needs to be hosted somewhere.

You could use a server to do that. But you already have a frontend application that doesn't need a server. Why not just go all in and have the backend not use a server as well!? So you'll see a lot of these frontend applications also use a headless and serverless backend.

That's why those two terms are often confused with one another.

You can have one without the other

That said, while this confusion exists, the reality is that you can have a headless WordPress site without a serverless backend. In fact, none of the headless WordPress sites have a serverless backend. They just host WordPress on a server.

That's because Ymir is the only platform that lets you deploy WordPress on serverless infrastructure. But at the same time, you can have a serverless WordPress site that isn't headless. The Ymir blog that you're reading this article on uses serverless, but it's not a headless WordPress site.

So there you have it, headless and serverless, two terms shrouded in mystery, but hopefully, demystified at last!

How serverless helps keep your WordPress site secure

Carl Alexander — Tue, 17 Aug 2021 15:56:00 +0000

Anyone who manages WordPress sites knows how critical it is to keep them secure. Every day thousands of sites get hacked. The consequence of that are often disastrous. They range from lost income to Google blacklisting the WordPress site.

WordPress itself has always been very secure. But we never use WordPress in a vacuum. We install themes and plugins. We need to host the WordPress site somewhere. All these are potential attack vectors that someone can use to hack your WordPress site.

Because of its nature, serverless PHP makes a lot of these attack vectors irrelevant. This is another reason why it can be a great way to host a WordPress site. (Besides the ridiculous scaling potential.) It doesn't matter whether you're using Ymir or not.

But how can serverless PHP can help keep your WordPress site secure? Well, the best way to understand is by going over serverless PHP architectural elements and how they affect these attack vectors.

Code deployed to serverless PHP is essentially read only

With serverless PHP, you can scale from 0 to thousands of connections in a minute. To do that, AWS Lambda and other similar services will always use the same code that you deployed with. And that code will always be read-only on the server that executes it.

This means that all vectors that rely on injecting PHP files into your WordPress installation don't work. We're talking injecting code in your themes, plugins, wp-config file, includes directory, etc. Those are all impossible because a Lambda function is read-only.

The only folder that isn't read only is /tmp. But even if someone injected files there, they wouldn’t be able to stick. That's because a Lambda function is ephemeral. It can exist one minute and be gone the next. Not to mention that it's only injected in one of hundreds of Lambda functions that could be running concurrently.

But for a code injection attacks to work, they need the code to actually stick to the server. And by its nature, serverless PHP doesn't allow this. This is why this whole category of attack vectors is a non-issue with serverless PHP.

It's also worth noting that this also means that the plugin and theme file editors won't work. This is also another common attack vector for injecting PHP code into your WordPress site.

Your uploads directory isn't on a server

Another common place for attackers to inject files is the uploads directory. You upload a file to it. And then you can just have PHP execute it by making a request to it.

That's why it's a common security practice to disallow PHP file execution in the uploads directory. That way, if someone injects a PHP file and requests it, they'll just download the file instead of having PHP execute it. With serverless WordPress, this is the only possible behaviour because your upload directory isn't on a server. It's on S3.

Full size

Above is a diagram of the serverless WordPress architecture. (To read more on it, check out this article.) As you can see, CloudFront sends all upload file requests to S3. They never make it to the PHP runtime that runs the PHP code.

Instead, when they make a request to that PHP file, CloudFront will just send the PHP file back. Exactly like if you requested a text file. This makes it impossible for an attacker to remotely execute a PHP file in the uploads directory.

Things that can still happen to you

Serverless only really protects you from attacks that target the file system. So while serverless will remove these common attack vectors, there are still things that you should be wary about.

SQL injection attacks

SQL injection is still something you have to worry about. If you have a plugin or theme with such a vulnerability, you can still get attacked that way. The best way to prevent attacks like these is to just follow standard security best practices.

Always keep your plugins and themes up to date.
Always download them from trusted sources.
Delete plugins and themes that you aren't using.

Brute-force attacks

Brute-force attacks can also still happen to you even if you use serverless. Much like with SQL injection attacks, you can protect yourself against these attacks by following security best practices.

Don't use the default "admin" username.
Use a two-factor authentication plugin. (There are a lot of them! This site uses Google Authenticator.)
Use a strong and uncompromised password. (I built a simple plugin that helps with this.)
Disable XML-RPC. (If you're doing everything else, this isn't as much of a problem.)

Denial-of-service attacks (DDOS)

In a similar vein as brute force attacks, you also have denial-of-service attacks (DDOS). This is something you can prevent using a web application firewall (WAF). Security plugins often come with a WAF or offer one as an external service.

If you're using Ymir or just running WordPress yourself on AWS, you can use AWS WAF. This is a full featured WAF with a lot of customizable options. That said, it also comes with a lot of pre-configured rules to help block known threats such as bots. But it also has a WordPress rule to block known vulnerabilities such as XML-RPC.

Ymir uses CloudFront to do page caching. If you also use CloudFront this way, you get some DDOS protection for free through AWS Shield. This will protect you against infrastructure layer attacks, but not application layers. (Also known as layer 7.) To protect against those, you need a WAF.

Worry-free WordPress security

None of what we just saw is exclusive to serverless. You can do all the things that serverless helps with using a regular server. You just need to either have access to it to configure it properly or use a WordPress host that uses security best practices.

The same goes with serverless and security plugins. There's nothing serverless does which you can't do with a security plugin. That said, security plugins are often a heavy-handed solution to security issues. They can often slow down your WordPress site significantly and cause other issues. With serverless, there's no performance impact to having a secure WordPress site.

And this is pretty much the benefit of serverless security. It's not better than what you can do yourself with a properly configured server and a security plugin. It's just a more worry-free way to keep a WordPress site secure. And there's something to be said to having that peace of mind.

Serverless WordPress architecture on AWS

Carl Alexander — Tue, 17 Aug 2021 15:35:14 +0000

Serverless PHP is a new exciting technology that has the potential to remove a lot of the burden of hosting PHP applications. One type of application that has the most to gain from serverless PHP is WordPress. Serverless PHP eases the burden of scaling WordPress while offering the same performance benefits that you'd get with a top tier host.

To understand how serverless PHP works with WordPress, we'll look at the current state of the modern WordPress server architecture. This architecture has evolved a lot over the last decade. (You can read more about it here.) Gone are the days of just hosting a WordPress site with an Apache server! There's a lot more to hosting a WordPress site now.

The good news is that hosting a serverless WordPress site looks a lot like it does with a modern WordPress server stack. The big change is that you're going to replace a lot of the architecture components with services from a cloud provider.

Now, the services that you'll use and how they fit together will vary from one cloud provider to another. With serverless PHP, the most popular cloud provider is AWS. That's why we'll focus on serverless WordPress architecture on AWS.

It's also worth noting that this is the same architecture that you'd get using Ymir. The only difference is that Ymir takes care of managing it all for you. (That's also why it's a DevOps platform.) But if you don't mind putting all the pieces together yourself or with the help of another tool (such as the serverless framework, this article will help you achieve that.

The modern WordPress server architecture

Let's begin with the modern WordPress server architecture. What does it like? Below is a diagram that shows the big picture of what's going on when a browser makes a request for a WordPress page.

Full size

Caching before PHP

First, the HTTP request your browser makes is going to hit a HTTP cache. This HTTP cache could be a combination of a content delivery network (also known as CDN) like Cloudflare, a dedicated server like Varnish or a page caching plugin. But whatever you're using, the goal is the same.

You want to cache WordPress responses.

That's because if PHP (and by extension WordPress) is a lot slower than your HTTP cache. So you want your HTTP responses to come from the HTTP cache as much as possible. If the HTTP cache can't respond to your request, then it'll forward the request to WordPress.

Caching on the PHP side

Once you hit PHP, things are a bit more straightforward. The higher the PHP version, the faster WordPress runs. That's why you always try to use the highest PHP version that WordPress supports.

The last point of optimization comes when WordPress makes queries to the MySQL database. These queries often account for most of the slowness that WordPress will have responding to your request. To make WordPress faster, you want to reduce the number of queries WordPress makes as much as possible.

You can achieve this by using an object cache plugin. An object cache plugin stores the results of a MySQL query in a high performance persistent cache. (Usually Memcached or Redis.) It then checks the cache before performing a query and returns the result if it was present. (Much like the HTTP cache does for our HTTP requests.)

This drastically reduces the time that WordPress takes to respond to a request. Especially if your WordPress project has plugins that make a lot of queries such as with WooCommerce. That's why it's an essential component of the modern WordPress server architecture.

Serverless WordPress architecture

Now that we've gone over the modern WordPress server architecture, let's look how it translates to serverless. The reason we went over it is that the essential components stay the same. The difference is that all these components are going to be handled by specific AWS services.

Full size

HTTP cache using CloudFront

So let's go back to our browser, the first thing that your HTTP request is going to hit is CloudFront. CloudFront is the AWS content delivery network. You can use it to do a lot of different things for your serverless WordPress site.

WordPress sites only use CloudFront (or any other CDN) to cache assets like CSS/JS files and media files. But you can also use it as a HTTP cache. This is where the real performance gains happen.

Using CloudFront as a HTTP cache will significantly reduce the response time of your WordPress site. But because CloudFront is also a content delivery network, this reduction applies to all visitors regardless of where they are in the world. This is a big difference compared to most WordPress HTTP cache solutions which aren't globally distributed.

If you'd rather not use CloudFront to do page caching, you can also configure it to just cache CSS/JS files and media files. You're also free to not use CloudFront and either use another content delivery network or none. But beware that performance won't be nearly as good without a content delivery network.

On the way to Lambda: API Gateway or Elastic Load Balancing

If CloudFront can't respond to a request, it'll forward the request to your serverless PHP application hosted on AWS Lambda. Now, much like a regular PHP application, a serverless PHP application isn't exposed to the internet. You need to use another service to act as an intermediary between the two.

With a regular PHP application, this would be the role of your web server. But with serverless PHP, there's no web server per se. Instead, you need to use one of two services to communicate with AWS Lambda. These are API Gateway or Elastic Load Balancing.

In general, you'll want to use an API gateway. (That's why it's the one shown on the diagram.) You should only use a load balancer is when you're dealing with hundreds of million of requests per month. (For example, you'll save several thousand dollars per month between serving a billion requests with a load balancer compared to an API gateway.) But most WordPress sites don't get that much traffic so using an API gateway is the cheaper option.

API gateway types

AWS also has two different API gateways: HTTP API and REST API. You can use either of them. That said, there are some important differences between the two.

First, there's the question of cost. The REST API costs more than the HTTP API. That's because the REST API has more features than the HTTP API.

What are these extra features? Well, it offers http-to-https redirection. But this isn't necessary if you use CloudFront to do page caching. It'll handle the http-to-https redirection.

It also offers edge optimized caching. But this is also something that CloudFront handles for us. In fact, you can't use both REST API edge optimized caching and CloudFront at the same time.

A REST API also supports wildcard subdomains. This is only important if you want to host a subdomain multisite installation. Otherwise, you don't need it either. (You can also work around the HTTP API limitation with wildcard subdomains by using CloudFront functions.)

This is all to show you that most of time you don't need the additional REST API features. So you're better off paying less and using the HTTP API instead.

Lambda

Once the request reaches either an API gateway or a load balancer, it gets converted to an event. This event triggers the Lambda function to run.

This Lambda function has two components. The PHP runtime which converts the event to a PHP FastCGI request. The other one is your WordPress project which is what the FastCGI request will run.

Now, you can create a PHP runtime but it's probably better to use an existing one. Bref is the popular open source PHP runtime for AWS Lambda so it's a good choice to pick. Otherwise, Ymir's PHP runtime is also open source.

ElastiCache

If you're using an object cache, you'll need a Memcached or Redis cache. ElastiCache is the AWS service that manages those. So you'll need to create one if you want to use a persistent object cache.

If you do decide to use one, be aware that you'll need to put your Lambda function on a private subnet to access it. This, in turn, will require a NAT gateway. You can also replace the NAT gateway with a specific EC2 instance that acts as the gateway. (You can read about how to do it here.)

VPC

This is a good time to bring up the virtual private cloud also known as VPC. AWS requires that certain resources such as your cache and database (which we'll see next!) be connected to a VPC. Some have to be on a private subnet (network without access to the internet) while others can also be on a public subnet (network with access to the internet).

If all you don't use ElastiCache, your interactions with a VPC are minimal. You'll just need a public subnet for the RDS database. Here's an updated diagram showing the VPC without ElastiCache.

Full size

Things are a more complicated if you need to use private resources like ElastiCache. This is where you need to add the NAT gateway discussed earlier. But you also need to change certain resources to use the private subnet such as your Lambda function. (By default, Lambda Functions don't need a subnet.)

You'll also need a bastion host to connect to the resources. A bastion host is an EC2 instance that acts as a bridge to the private subnet. For example, a bastion host is necessary if you want to connect to your database server if it's on the private subnet.

Full size

Above is a diagram showing the same architecture with ElastiCache, NAT gateway, bastion host and the private subnet. As you can see, there are more moving parts. It's also more complicated in terms of VPC configuration.

RDS

The last component of our serverless WordPress architecture is the database. RDS is the service that manages relational databases like MySQL and MariaDB.

If you use a public subnet, your database is going to be publicly accessible. This isn’t much a security problem as long as you don’t share the database server address. But this makes the use of a strong password when creating it even more important.

That said, if it’s on a private subnet, you should set a strong password anyway! But you don’t have to worry about the database being publicly accessible. However, like we mentioned with the VPC, you’ll need to create a bastion host to connect to it.

What about media uploads?

One thing we haven't talked about yet is uploads. What happens to uploads when you don't have a server? Well, that part is a lot more complicated than what we've seen so far!

Full size

Above is an updated diagram showing you what our serverless WordPress architecture looks like with media uploads. Things start off the same with requests going through CloudFront. Once the request hits CloudFront, it'll decide whether this is a serverless PHP request or a request for a media file. (Not just an uploaded file)

If it's a media file, the request instead goes to S3 which is the most well known AWS service. It's a file storage service that lets you store files in the cloud inexpensively. There are a lot of WordPress plugins that let you upload files to S3.

How most S3 plugins work

That said, there are some notable differences when you use S3 with serverless WordPress compared to a plugin. The biggest one is how you send your WordPress media files to S3. With a plugin, it looks like this:

You upload a media file to your WordPress server like you would normally without a plugin. The plugin itself takes care to upload the file to S3 once it's on the server. Most of the time, this happens in the background using a WordPress cron.

How does file uploads work with S3 and serverless WordPress?

With serverless, you can't do that because there's no server to upload the file to first. Instead, you need to upload it to S3 right away. The proper way to do that is to use a signed URL.

A signed URL is a temporary URL that you can use to perform an operation on S3. So what you need to do is contact S3 and it'll create a signed URL. You then use this signed URL to upload the file to S3 without compromising your security.

This is a lot harder to do in practice since WordPress doesn't make it easy to take over this process. You also don't have direct access to the files on the server to create the different file sizes either. So you need to develop a way to create those as well.

This is by far the more complicated aspect of the serverless WordPress architecture. It's not really because of anything specific with AWS. It's just because WordPress is an old piece of software. Its creators designed it assuming you'd always have a server to upload files to. (The same with most S3 upload plugins as well.) There's no simple way to tell it you don't want to do it.

That said, WordPress is very extensible. You can write a plugin (like the Ymir one) that can hijack the WordPress media upload process. (Another plugin that supports direct upload is Media Cloud.) That's what's necessary for it to work with serverless.

Different, but also familiar

As you can see, a serverless WordPress installation isn't quite the same as a modern WordPress server architecture. But it's grounded in the same fundamentals. It's just that you have to rely on services from cloud providers like AWS.

But that's also what a lot of hosts already do. They rely on services like a content delivery network (CloudFront), managed databases (RDS) and managed Redis caches (ElastiCache). So there are some similar elements between the two.

But as the issue with media uploads highlighted, a lot of the architectural challenges with serverless come from WordPress itself. It's not that it can't run on Lambda. It's that some of its inner workings assume there will always be a server present.

That said, overcoming these issues can be worthwhile. This is especially true if you need to scale WordPress or, even more so, WooCommerce. Serverless offers unparalleled scaling potential. That's also why it's the ideal platform for WooCommerce.

What is serverless PHP and how does it work?

Carl Alexander — Thu, 24 Jun 2021 17:53:34 +0000

Serverless computing is a new cloud computing model centred on Functions as a Service (FaaS). A serverless PHP application is simply a PHP application that runs on one of those serverless computing platforms. But what's so special about it, and why is there interest in using it instead of a regular server for PHP?

Well, as web developers, we always have to consider where we host our code. It doesn't matter whether we're using JavaScript, PHP, Python or Ruby. (Just to name a few.) They all need a hosting service where that code can run and render the HTML sent to the browser.

There are a lot of different hosting services. You can pay for a server on DigitalOcean or some other some other cloud provider. This is often the cheapest option, but then you have a server to manage.

If you don't want to do that, you can use a Platform as a Service (PaaS) like Heroku. You tell them how big of a server you want and they take care of the rest. On your end, you just need to deploy your code and that's it. WordPress hosting works similarly.

While platforms as a service help you worry less about your server, they don't completely remove all server issues. You still have to wonder if you can handle spikes in traffic. That's because most of these services won't scale automatically to handle these scenarios.

Serverless computing offers a solution to this problem. It distills your cloud computing needs to its barest essence. Your cloud provider will run your code on-demand and only charge you for that.

This lets you only pay for what you use. (If your site receives no traffic, you pay nothing.) This architecture also lets you scale infinitely. In fact, serverless computing can scale to handle thousands of visitors almost instantly.

This is a transformative change for all programming languages. But even more so for PHP, since it's a language uniquely positioned to leverage the benefits of serverless. Let's explore why that is.

How does a traditional PHP application work?

PHP differs from most other programming languages because it's an interpreted language. You don't need to compile your code. You can just upload your PHP files to a web server, and that's it.

The web server (nginx or apache most of the time) does all the magic. It figures out what PHP file you're trying to access. Often, it's just the index.php file in the root directory which then loads other PHP files. (Fun fact: Pieter Levels makes $100k/month from a single index.php file!)

The web server then sends this PHP file to the PHP interpreter. The interpreter reads the file, parses it and then executes it. Once the execution completes, it'll return some output. That output is the generated HTML that the web server sends back to your browser as an HTTP response.

What happens when you use serverless PHP

Now that we've gotten a basic idea of how a PHP application works, we can look at what happens to it when you use serverless PHP. First, serverless computing is event-driven. Your serverless PHP interpreter awaits for an event, and this triggers the PHP code to run.

In a way, it’s similar to how things work with a web server. Your web server receives an HTTP request (an event) and this event would cause the web server to tell the PHP interpreter to process your code. This is the primary reason serverless computing works so well with PHP.

So what's different about serverless PHP then? The big change is that, not only do you not have a server with serverless PHP, you don't have a web server anymore either. Instead of a web server, you use an API gateway which is a special service offered by the cloud provider. Let's look at what that looks like in more detail.

The life of a serverless PHP request

Below is a diagram showing what happens when you make a request to a serverless PHP application. As you can see, it looks very similar to what we had before.

The browser sends the HTTP request to the API gateway. The gateway receives the HTTP request, converts it to an event, and forwards it to the serverless PHP application. It reads, parses, and executes the requested PHP file and returns the result to the API gateway. The gateway generates the HTTP response and sends it back to the browser.

Of note is the serverless PHP application. It has two parts: the PHP runtime and your PHP code.

The PHP runtime contains the PHP interpreter. But it also has code to process the event sent by the API gateway and return it the response from the interpreter. Your PHP application code is the same PHP code you’d deploy to a regular server.

These two parts get packaged together as a function (this is where the name Function as a Service comes from) when you deploy your serverless PHP application to the cloud provider. This function is what the API gateway sends an event to whenever it receives a request.

What's the advantage of this?

Now that we've seen how serverless PHP application works, you might wonder, "Why would I want to use this instead of my trusty Linux server?"

Near infinite scaling

Once you've deployed a new version of your serverless PHP application, the cloud provider can create as many copies of it as necessary. It can also create these copies almost instantly. This allows your PHP application to handle large spikes of traffic without breaking a sweat. (For example, Ymir can help your WooCommerce site scale to handle hundreds of customers instantly.)

With a normal server setup, you need to have the server capacity already provisioned and ready to go. Otherwise, you need to have a horizontally scaling setup ready to handle these traffic spikes. But these types of setup take a few minutes to scale which can make the application unavailable until then.

No need to manage servers

This is a good way to bring up the next advantage of using serverless. You don't have a server to manage anymore. If you've ever had to manage servers, you know the responsibilities that come with managing one. (Being on call when it goes down, handling updates, keeping it secure, etc.)

With serverless, all that you have to do is deploy your PHP code to your serverless platform and you're good to go! This gives you a peace of mind that's hard to put a price on. But once you've experienced it, it's hard to go back. (It's why I built Ymir.)

Pay per use

The server doesn't just change how we host our code. It's also changes how we pay for hosting it. Before you'd pay for a server that had to stay on at all times. This was true regardless that you had a droplet on DigitalOcean or code deployed to a Heroku dyno.

With serverless, you only pay when your code runs. (For example, AWS Lambda charges you by the millisecond!) In a lot of cases, this offers significant cost saving. One case study shows how external.io went from paying $50/month on platform.sh to ~$17/month on AWS.

The tradeoffs

If serverless sounds too good to be true, that's because it generally is! That said, it's not the ideal solution in all situations. Here are some the tradeoffs you have to consider if you're looking to use serverless,

Harder to predict costs

When you pay for a server, you know it'll be $X/month. It's simple and easy to plan for. If you need a larger server, you know you'll go from paying $X/month to $Y/month.

With serverless that whole cost calculation is more complicated, you have to think, "How many requests do I get? How long do they last on average?" So while pay per use pricing model offers great cost saving potential, you might prefer the predictability of regular hosting costs. Even if you might pay 2-3 times more for it.

Not cheaper than a low-end VPS

If you're running your PHP application on a $5/month VPS, serverless won't offer any cost saving. In general, serverless PHP becomes cost competitive when you're paying $25/month for hosting. $25/month isn't that expensive for hosting, but a lot of us just host projects on smaller VPCs.

That said, it's also disingenuous to just compare server costs like this. You should also consider how much it costs to manage that server. Either it costs your time or you have to pay someone to do it.

Generally limited to AWS

While serverless computing exists on all the major cloud providers, your serverless architecture is very provider dependent. An API gateway on Microsoft Azure won't work the same as the one on Google Cloud.

The reality is that, at this time, most of the energy around serverless PHP is focused on one provider: AWS. Not everyone can use AWS for a wide range of reasons. That said, if you can't use AWS, you're going to have a harder time finding resources or services (Laravel Vapor and Ymir are both AWS only) to create a serverless PHP application.

A great alternative to servers

The point of this article wasn't necessarily to show you you shouldn't host a PHP application on a server. Hosting a PHP application on a server still has a bright future ahead of it. It's sometimes more cost effective to do so. You can choose which provider you want to use, and there are countless resources and tools to help you manage one.

But if you're using an expensive hosting provider or a platform as a service or some complex horizontally scaling setup, serverless might be the thing you're waiting for. It's easier to manage and deploy to while often costing less.

And that's something to be excited about.

Why serverless is the perfect hosting solution for WooCommerce

Carl Alexander — Wed, 31 Mar 2021 21:17:44 +0000

Serverless computing isn't discussed much in the WordPress community. But it has the potential to transform how WordPress sites scale and perform.

No WordPress platform has more to gain from serverless computing than WooCommerce. Hosting a WooCommerce site comes with unique challenges that you don't have when hosting a regular WordPress site. That's why a lot of managed WordPress hosting companies started to offer dedicated WooCommerce hosting.

Serverless is the perfect technological solution to tackle those challenges. That's why you'll probably start hearing more and more about it.

How do you host a regular WordPress site?

But before we go over the main issue with hosting WooCommerce sites, it would be useful to look at how you host a high traffic WordPress site. While the implementation can vary from host to host, the general architecture is essentially the same. It looks like the diagram below:

Whenever a browser makes a request for a WordPress page, the first thing that a WordPress host will try to do is serve a cached version of that page. If the WordPress host doesn't do page caching, then you might have a caching plugin handling it. But, in general, a high performance WordPress site will have one.

The reason a WordPress host wants to use page caching is to reduce the number of requests that make it to PHP. PHP is a lot slower than serving a page using a page cache. It's also a lot more taxing on the server.

This last bit is the important thing to keep in mind. A page cache can serve thousands of requests per minute without your server breaking a sweat. But because of its resource needs, PHP can only handle a fraction of that, even if you have a massive server.

So if these thousand of requests handled by the page cache went to PHP instead, it would take down the server. Which is what you often see if someone without a page cache receives a sudden burst of traffic. The site becomes unavailable.

But not all WordPress pages can use a page cache. For example, you can't cache the WordPress login page or the admin. PHP has to be the one sending the response for these pages.

It's all about the cart

This brings us to WooCommerce. The architecture for hosting a WooCommerce site looks exactly the same as the one for hosting a WordPress site. You have a page cache, PHP, a database.

The problem is the pages that a page cache can't cache. More specifically, a certain part of the page: the cart. You can't cache a cart because it's unique to each visitor. And since the cart appears on every page, it means that you can't cache a page once a cart isn't empty.

This is why I mentioned the scenario about request suddenly going from the page cache to PHP. That's exactly what happens when you add an item to a cart. The requests go from being served from the page cache to being served by PHP because the cart isn't empty.

Now, this isn't a big deal if you have a few people adding items to cart.

But what happens if there's a sale? Well, you now have hundreds of people with items in their cart. Each cart can't be cached so your number of PHP requests explodes takes down the server.

If you're using a specialized WooCommerce host, they mitigate this scenario by giving you a larger server than you'd have with a regular WordPress site. This is one reason they charge more. That said, this only works as long as you don't have any huge sales spikes.

If your WooCommerce site is more of the type to have those, you're in a tough position. Either you’re paying for those potential spikes all the time. Or you're not, and your site might go down during the most critical time in your business.

How does serverless tackle this problem?

So how does a serverless PHP solution like Ymir fix this issue?

It all comes down to the very nature of serverless computing. Now, the name serverless is misleading. There are still servers somewhere. You just don't have to worry about them.

In theory, this isn't very different from a managed WordPress host either. That said, there's one big difference versus a managed WordPress host: it's that you don't have to worry about the power of your server either.

With serverless, each time you make a call to PHP, a small server gets created to process it. When PHP finishes processing the request, the server gets shut down unless there's another request to process. This is all done automatically for you.

Now, if you're receiving a high volume of requests, serverless computing will create as many servers as necessary to process them. This scaling happens automatically in seconds, and there aren't any limits to how many of these PHP servers you can have.

Above is a simplified diagram of our serverless WordPress architecture. It's very similar to our earlier architecture, but now we don't have one server. Instead, we have an infinite pool of potential PHP servers to handle our traffic.

It's easy to see how this architecture can help mitigate the cart issue when hosting a WooCommerce site. Since there's no more "server", you're no longer limited by the number of requests PHP can handle. So if your WooCommerce site sees a spike in sales, your infrastructure will scale to handle the traffic.

Once that spike ends, everything scales back down. So you're not stuck paying for a large server to handle those potential spikes or stressed wondering if your site will go down during a sale. It's a weight off your shoulders and wallet!

Can't you get a host that autoscales?

Container orchestration technologies such as Kubernetes are powerful platforms that offer similar infinite scaling potential. Some hosts have already started relying on it to scale their internal infrastructure. So you might be wonder how that technology compares.

The problem is that scaling with Kubernetes is a lot slower than with serverless. It relies on a cluster autoscaler to determine when to scale and add nodes. Since the autoscaler relies on resource signals to determine when to scale, this creates a lag in the scaling.

That's why it takes, in the best-case scenario, about a minute for Kubernetes to spin up a new node. At worst, several minutes.

By the time that node comes up, it's often too late. Your WooCommerce site has been unresponsive for a while. You're also constantly trying to play catch up trying to match your infrastructure needs to the current demand.

AWS Lambda scales the moment a request cannot get processed. There's still a cold start to the new Lambda which creates a bit of lag. That said, it's a few seconds compared to minutes.

What about the database?

You probably noticed that we haven't talked about the database yet. Unfortunately, while serverless databases exist, their cost and performance isn't quite there yet. So while serverless will solve the problem with carts overwhelming your PHP server, the same isn't true for databases. (At least, not yet!)

This means that we still have a similar problem as before. If you're not careful, the PHP servers that serverless computing creates can overwhelm your database server. Does that mean that we're out of luck?

No, of course not! This database problem is something hosting companies have to contend with as well. But the larger positive is that database servers are a lot more performant than a PHP server and harder to take down.

How hard are they to take down? Well, look no further than this Twitter thread discussing load testing done on WooCommerce running on AWS Lambda. The real kicker is this one:

A $13/month RDS database was able to handle at least 300 concurrent customers checking out at the same time with no object cache. You'd need a massive server with a lot of PHP workers to handle that much traffic. WordPress hosts will charge several hundred dollars per month for such a server.

But with serverless, you have access to it on demand, and you don't have to pay for anything when there's no traffic. So not only are you capable of handling massive traffic spikes, it'll also cost you less to do so. (It's not completly free because you still have the database to pay for.) It's a win-win scenario!

A new beginning

Serverless is still in its early days. But seeing how it trivializes hosting server intensive platforms like WooCommerce is really mind-blowing.

If you run a WooCommerce store, you shouldn't worry about your server whenever you have a spike in sales. You should have confidence that it can handle anything that you can throw at it.

With serverless, we're closer to this than ever before.

How to test Stripe Checkout and Customer portal with Laravel Dusk

Carl Alexander — Thu, 04 Mar 2021 06:44:13 +0000

Recently, I added billing to Ymir. It's a Laravel application, and adding payment functionality to it was a breeze with Laravel Cashier. Cashier supports different payment gateways, but it was originally designed for Stripe. It's also what I'm using with Ymir.

Over the last year or so, Stripe has released two products to ease the engineering burden dealing with payments. First, there's Checkout, which lets you not worry about building a payment page. Second, there's the customer portal which lets people manage their subscription and billing information.

Laravel Cashier has support for both Checkout and the Customer portal, which means you don't have to code any payment backend. But that doesn't mean that you don't want to test the integration between Stripe and your Laravel application. After all, payment is one of the most important part of your application!

To do that, you'll want to use Laravel Dusk to do browser testing for your application. If you're not doing Browser testing already, you should consider looking into it. You could use another framework, but Dusk is the standard in the Laravel ecosystem.

Getting webhooks to work during tests

Doing browser testing with Stripe Checkout and the Customer portal comes with certain challenges. The biggest one is that these products communicate with your application via webhooks. When developing your Laravel application, you use the Stripe CLI to forward webhooks to it.

We'll also need to do that when we run our browser tests. So an important aspect of using Laravel Dusk is having the Stripe CLI to forward our webhooks during the tests. We need to automate that as part of the test suite.

A simple way to automate the use of the Stripe CLI is to run it as a background process during our tests. We can use the PHPUnit setUp and tearDown methods to do it. Whenever we need the Stripe CLI, the setUp method starts the process and then stops it in the tearDown method.

namespace Tests\Browser;

use Symfony\Component\Process\Process;
use Tests\DuskTestCase;

class StripeTest extends DuskTestCase
{
    /**
     * @var Process
     */
    private $process;

    protected function setUp(): void
    {
        parent::setUp();

        $this->process = new Process(['stripe', 'listen', '--api-key', env('STRIPE_SECRET'), '--forward-to', sprintf('%s/stripe/webhook', env('APP_URL'))]);
        $this->process->start();
    }

    protected function tearDown(): void
    {
        parent::tearDown();

        $this->process->stop();
    }
}

Above is the base test case class you can use to scaffold the Stripe CLI. It uses the Symfony Process component to run the process in the background. It runs until the stop method gets called in the tearDown method.

The code expects two environment variables to be present. First, there's the STRIPE_SECRET environment variable containing your Stripe secret key. This allows the Stripe CLI to login without you having to enter your email and password. (You can read more about it here.)

Second, there's the APP_URL environment variable. We use it to generate the URL to pass to the --forward-to option. The --forward-to URL is where the Stripe CLI will forward webhook requests from Stripe. The default route with Laravel Cashier is /stripe/webhook so we just prepend the APP_URL environment variable to it.

Cleaning up the customer after a test

Another challenge with testing the Stripe Checkout and Customer portal is cleaning up after the tests. You don't want to end up with hundreds of customers in your Stripe test environment. So you need to set up your test classes so that they can clean up any customer they might have created.

A simple way to achieve this is by storing the created customer in your test class. Once the test completes, you delete the customer in Stripe. Here's one way you could do this.

namespace Tests\Browser;

use App\Model\User;
use Stripe\Customer;
use Stripe\Exception\InvalidRequestException;
use Stripe\Stripe;
use Symfony\Component\Process\Process;
use Tests\DuskTestCase;

class StripeTest extends DuskTestCase
{
    /**
     * @var Process
     */
    private $process;

    /**
     * @var User
     */
    private $user;

    protected function setUp(): void
    {
        parent::setUp();

        $secret = env('STRIPE_SECRET');

        $this->process = new Process(['stripe', 'listen', '--api-key', $secret, '--forward-to', sprintf('%s/stripe/webhook', env('APP_URL'))]);
        $this->process->start();

        Stripe::setApiKey($secret);
    }

    protected function tearDown(): void
    {
        parent::tearDown();

        $this->process->stop();

        if ($this->user instanceof User) {
            try {
                (new Customer($this->user->stripe_id))->delete();
            } catch (InvalidRequestException $exception) {
            }
        }

        $this->user = null;
    }
}

Above is the updated code sample from earlier. We added a few more things to take care of the customer cleanup. If you'd rather do this clean up inside each of your tests, you don't have to add any of this code.

First, there's a new user property. It'll store the User model object that has the Stripe customer ID that we want to clean up. (If you're using another model to store the Stripe customer ID, you should store that model instead.) During your tests, if you create a User model, you want to assign it to that property instead of creating a variable for it.

Next, there's a minor change in the setUp method. We added code to initialize the Stripe PHP SDK by calling the setApiKey method. We pass it the API secret key which Laravel Cashier expects to be in STRIPE_SECRET environment variable by default.

After that, in the tearDown method, we added code to delete the customer in Stripe. We start by checking if the user property has a User object stored in it. If it does, we call the code to delete the customer in Stripe.

To delete the customer, we create an instance of the Stripe Customer class using the ID stored in the User model. We then call the delete method. We put that code in a simple try-catch block. This is so we can discard errors if the customer didn't exist in Stripe.

Creating page classes for Stripe

This wraps up the base test class. Next, we want to look at what we need to create page classes. Page classes are a good way to group actions you want to perform on specific web pages.

With Stripe, we need a page class for both the checkout page and the customer portal. Both will share some similar elements. To begin, let's create the checkout page class. (You can do this with the php artisan dusk:page command.)

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;

class Checkout extends Page
{
    /**
     * Get the URL for the page.
     */
    public function url(): string
    {
        return '/';
    }

    /**
     * Assert that the browser is on the page.
     */
    public function assert(Browser $browser)
    {
        $browser->assertPathIs($this->url());
    }

    /**
     * Get the element shortcuts for the page.
     */
    public function elements(): array
    {
        return [
            '@element' => '#selector',
        ];
    }
}

Above is what you'd get if you ran the command php artisan dusk:page Checkout. The command creates a Checkout class with some methods. We only care about the url and assert methods for this article so we won't discuss the elements method.

Asserting external URLs

Now, by default, Dusk lets you test pages that aren't part of your Laravel application. You can just replace the value returned by url method by a full URL. You then use the method assertUrlIs to check the URL in the assert method.

The issue is that the Stripe URLs are dynamic. So the assertUrlIs method won't work to validate that we're on the right page. To fix this, we'll need to create a macro to add a custom assertion method in the Browser class.

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Laravel\Dusk\Browser;

class DuskServiceProvider extends ServiceProvider
{
    /**
     * Register Dusk's browser macros.
     */
    public function boot()
    {
        Browser::macro('assertUrlBeginsWith', function (string $url) {
            $pattern = str_replace('\*', '.*', preg_quote($url, '/'));

            $segments = parse_url($this->driver->getCurrentURL());

            $currentUrl = sprintf(
                '%s://%s%s%s',
                $segments['scheme'],
                $segments['host'],
                Arr::get($segments, 'port', '') ? ':'.$segments['port'] : '',
                Arr::get($segments, 'path', '')
            );

            PHPUnit::assertThat(
                $currentUrl,
                new RegularExpression('/^'.$pattern.'/u'),
                "Actual URL [{$this->driver->getCurrentURL()}] does not begin with the expected URL [{$url}]."
            );

            return $this;
        });
    }
}

Above is the modified DuskServiceProvider class with the macro for the assertUrlBeginsWith method. It's a method that checks if the URL starts a specific way, but it doesn't have to be identical.

The code itself is nearly identical to the assertUrlIs method. The only change was to remove the $ in the regular expression. This changes the regular expression from requiring an exact match to just having the string begin with a specific URL.

Modifying the assert and url methods

With our macro created, we can go back to our Checkout class. We're going to fill in the assert and url methods. After the changes, our Checkout class will look like this:

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;

class Checkout extends Page
{
    /**
     * Assert that the browser is on the page.
     */
    public function assert(Browser $browser)
    {
        $browser->assertUrlBeginsWith($this->url());
    }

    /**
     * Get the URL for the page.
     */
    public function url()
    {
        return 'https://checkout.stripe.com/pay';
    }
}

The url method returns https://checkout.stripe.com/pay which is the URL that all Stripe Checkout links start with. The assert method passes that URL to our macroed assertUrlBeginsWith method to check the page URL starts with the URL. We then do the same thing for the Stripe customer portal.

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;

class CustomerPortal extends Page
{
    /**
     * Get the URL for the page.
     */
    public function url()
    {
        return 'https://billing.stripe.com/session';
    }

    /**
     * Assert that the browser is on the page.
     */
    public function assert(Browser $browser)
    {
        $browser->assertUrlBeginsWith($this->url());
    }
}

The CustomerPortal class is also nearly identical to the Checkout class. We just changed the URL returned by the url method. The customer portal URL starts with https://billing.stripe.com/session.

Testing Stripe subscription

Now, we have all we need to write our browser tests. These tests are going to vary from one Laravel application to another. But we can go over a small hypothetical one that goes over some common operations you might want to do.

namespace Tests\Browser;

use Symfony\Component\Process\Process;
use Tests\DuskTestCase;

class StripeTest extends DuskTestCase
{
    // ...

    public function testSubscribe()
    {
        $this->browse(function (Browser $browser) {
            $this->user = User::factory()->create();

            $this->assertTrue($this->user->subscriptions->isEmpty());

            $browser->loginAs($this->user)
                    ->goToBilling()
                    ->on(new Checkout())
                    ->enterValidCreditCard()
                    ->enterNameOnCreditCard($this->user->name)
                    ->enterAddress()
                    ->subscribe()
                    ->on(new CustomerPortal());

            $this->user = $this->user->refresh();

            $this->assertTrue($this->user->subscription()->active());
        });
    }
}

Above is the updated StripeTest class with our sample test called testSubscribe. It tests that a subscription gets created in our Laravel application when we enter a valid credit card in the Stripe Checkout. Once subscribed, we should get redirected to the customer portal. (You can do this by setting the checkout return URL to the application URL that redirects to the customer portal.)

Walking through the test code, it starts by creating a User using its model factory. We then do a quick assertion to check that the user has no subscriptions. You can skip this if you prefer.

Browser actions

After that, we start our test by performing browser actions through the Browser class. First, we need to ensure that the browser is logged in by using the loginAs method.

Then we have goToBilling method. This is a hypothetical method that represents whatever actions you'd need the browser to do to get to and click the Stripe checkout link in your Laravel application. Clicking that link should then send us to the Stripe checkout page.

We verify this by using the on method with the Checkout class we created. Because of the changes we did earlier, Dusk should correctly detect that the browser is on a Stripe checkout page.

Checkout class methods

Once we know that we're on the Stripe checkout page, we need to enter the payment information. We do that with some page methods. For clarity, we did one page method per form section. But if you'd prefer one for the entire process, that's fine too.

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;

class Checkout extends Page
{
    // ...

    /**
     * Enter an address.
     */
    public function enterAddress(Browser $browser)
    {
        $browser->select('#billingCountry', 'CA')
                ->type('billingPostalCode', 'H0H0H0');
    }

    /**
     * Enter the name on the credit card.
     */
    public function enterNameOnCreditCard(Browser $browser, string $name)
    {
        $browser->type('#billingName', $name);
    }

    /**
     * Enter a valid credit card.
     */
    public function enterValidCreditCard(Browser $browser)
    {
        $browser->type('#cardNumber', '4242424242424242')
                ->type('#cardExpiry', '0129')
                ->type('#cardCvc', '111');
    }

    /**
     * Press the subscribe button.
     */
    public function subscribe(Browser $browser)
    {
        $browser->press('Subscribe')
                ->pause(20000);
    }
}

Above is the updated Checkout class with the new page methods. Most of the values for the form are hardcoded. (Fun fact: H0H 0H0 is the Santa Claus' Canadian postal code.) If you'd rather pass them as arguments, that's ok as well. You're really free to build out these methods in the way that makes the most sense to you.

It's worth noting that you can't change the 4242424242424242 credit card number. It's the valid Visa credit card number that Stripe will accept in test mode. (You can view all the different card numbers in the Stripe documentation.) The CVC number can be anything, and the expiry date only needs to be a future date.

Another thing that might be unusual is the call to the pause method after pressing the subscribe button. You don't have to put the pause there, but a pause is necessary. You need to give Stripe the time to process the request, but also send over the subscription information to your Laravel application via the Stripe CLI.

20 seconds is enough time in my experience. I tried lower values, but sometimes the tests would fail. So be aware if you choose to put a smaller pause time.

Redirecting to the customer portal

After you subscribe, you’ll notice that our test expects Stripe to redirect us to the customer portal. To do that, you need to set up a route in your application that redirects to the customer portal. The Cashier documentation shows how you can do that.

use Illuminate\Http\Request;

Route::get('/billing-portal', function (Request $request) {
    return $request->user()->redirectToBillingPortal();
})->name('billing-portal');

You then want to use that route when creating your Stripe checkout link.

$checkout = Auth::user()->newSubscription('default', 'price_xxx')->checkout([
    'success_url' => route('billing-portal'),
    'cancel_url' => route('your-cancel-route'),
]);

Verifying the subscription

Once we're done testing with the browser, we want to check that our Laravel app received the changes from the Stripe API. To do that, we need an up-to-date version of our user. So we need to reload the model using the refresh method.

After that, we need to get the Subscription model for the user. If all worked well, you should have one. We then check that the subscription is active by asserting that the active method returns true.

Test cancelling an active subscription

Lastly, we’ll look at a test using the customer portal. There are a few tests you can do there, but the one we’ll look at is cancelling an existing subscription. Below is the updated StripeTest class:

namespace Tests\Browser;

use Symfony\Component\Process\Process;
use Tests\DuskTestCase;

class StripeTest extends DuskTestCase
{
    // ...

    public function testCancelSubscription()
    {
        $this->browse(function (Browser $browser) {
            $this->user = User::factory()->create();

            $this->user->newSubscription()
                       ->create('pm_card_visa');

            $this->assertFalse($this->user->subscription()->cancelled());

            $browser->loginAs($this->user)
                    ->goToBilling()
                    ->on(new CustomerPortalPage())
                    ->cancelSubscription();

            $this->user = $this->user->refresh();

            $this->assertTrue($this->user->subscription()->cancelled());
        });
    }
}

This test starts the same as the one to test the subscription checkout flow. We create a user using the model factory.

But after that, we create a Stripe subscription using the newSubscription method followed by the create method. This will create a subscription in Stripe using the given payment method ID. pm_card_visa is the payment method ID of a Visa credit card in the Stripe test environment.

Once the Stripe subscription created, we do a quick sanity check to check that the subscription isn’t in a cancelled state. Once that’s done, we can start performing the browser actions. There’s only one specific one for the customer portal for this test. It’s clicking on the cancel subscription button.

But first, we need to navigate to the customer portal. We’re going to use the goToBilling method again for that. Then we ensure that we're on the customer portal using the on method. Then we can cancel the subscription.

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;

class CustomerPortal extends Page
{
    // ...

    /**
     * Cancel an active subscription.
     */
    public function cancelSubscription(Browser $browser)
    {
        $browser->clickLink('Cancel plan')
                ->pause(5000)
                ->press('Cancel plan')
                ->pause(10000);
    }
}

Above is the cancelSubscription method. On the Stripe customer portal, you need to click on “Cancel plan” twice to cancel your subscription. The first time you’re clicking on a link and the second time it’s a button. A pause is necessary between both clicks to allow the site to react to the first press.

The second pause is there for the same reason as the one for testing the subscription. It allows Stripe to communicate back to the Laravel application via the Stripe CLI.

The test also wraps up similarly as the subscription one. We reload the User model to load the changes from the Stripe. We then do an assertion to ensure that the subscription is in a cancelled state.

A good foundation

So with this, you have enough to test a subscription with Stripe checkout and a cancellation using the customer portal. There are still a lot of other scenarios you might want (and should!) to test. But this should give you the foundation you need to make writing those tests a breeze!

What is software complexity and how can you manage it?

Carl Alexander — Wed, 20 Jan 2021 04:19:07 +0000

As developers, we spend a lot of time writing code. But we spend even more time maintaining that code. How often do we go back find that that code has become this tangled mess that we almost can’t understand? It's probably more often than we want to admit!

We wonder, "How did this happen? How did this code get so messy?" Well, the most likely culprit is software complexity. Our code became so complex that it became hard to know what it did.

Now, software complexity isn't a topic that developers are often familiar with when they start coding. We have other things to worry about. We're trying to learn a new programming language or a new framework.

We don't stop and think that software complexity could be making that job harder for us. But it is doing precisely that. We're creating code that works, but that's also hard to maintain and understand. That's why we often come back and ask ourselves, "What was I thinking!? This makes no sense."

That's why learning about software complexity is important. It'll help you increase the quality of your code so that these situations don't happen as often. And this also has the added benefit of making your code less prone to bugs. (That's a good thing even if debugging is a great learning tool!)

What is software complexity?

Let's start by going of software complexity as a concept. Software complexity is a way to describe a specific set of characteristics of your code. These characteristics all focus on how your code interacts with other pieces of code.

The measurement of these characteristics is what determines the complexity of your code. It's a lot like a software quality grade for your code. The problem is that there are several ways to measure these characteristics.

We're not going to look at all these different measurements. (It wouldn't be super useful to do so anyway.) Instead, we're going to focus on two specific ones: cyclomatic complexity and NPath. These two measurements are more than enough for you to evaluate the complexity of your code.

Cyclomatic complexity

If we had to pick one metric to use for measuring complexity, it would be cyclomatic complexity. It's without question the better-known complexity measurement method. In fact, it's common for developers often use the terms "software complexity" and "cyclomatic complexity" interchangeably.

Cyclomatic complexity measures the number of "linearly independent paths" through a piece of code. A linearly independent path is a fancy way of saying a "unique path where we count loops only once". But this is still a bit confusing, so let's look at a small example using this code:

function insert_default_value($mixed)
{
    if (empty($mixed)) {
        $mixed = 'value';
    }

    return $mixed;
}

This is a pretty straightforward function. The insert_default_value has one parameter called mixed. We check if it's empty and if it is, we set the string value as its value.

How to calculate cyclomatic complexity

You calculate cyclomatic complexity using a control flow graph. This is a graph that represents all the possible paths through your code. If we converted our code into a control flow graph, it would look like this:

Our graph has four nodes. The top and bottom ones are for the beginning and end of the insert_default_value. The two other nodes are for the states when empty returns true and when it returns false.

Our graph also has four edges. Those are the arrows that connect our four nodes. To calculate the cyclomatic complexity of our code, we use these two numbers in this formula: M = E − N + 2.

M is the calculated complexity of our code. (Not sure why it's an M and not a C.) E is the number of edges and N is the number of nodes. The 2 comes from a simplification of the regular cyclomatic complexity equation. (It's because we're always evaluating a single function or method.)

So what happens if we plug our previous numbers into our formula? Well, we get a cyclomatic complexity of M = 4 − 4 + 2 = 2 for the insert_default_value function. This means that there are two "linearly independent paths" through our function.

This is pretty easy to see in our updated graph above. One path was for if our if condition was true and the other was for if it wasn't. We represented these two paths with red arrows on each side of the control flow graph.

Alternative way to calculate it

Now looking at what we just did, it's pretty clear that cyclomatic complexity isn't that user-friendly. Most of us don't have mathematics degrees. And we sure don't want to draw graphs and fill values in formulas while we're coding!

So what can we do instead? Well, there's a way to calculate the cyclomatic complexity without having to draw a graph. You want to count every if, while, for and case statements in your code as well as the entry to your function or method.

function insert_default_value($mixed)  // 1
{
    if (empty($mixed)) {               // 2
        $mixed = 'value';
    }

    return $mixed;
}

It's worth noting that with if statements you have to count each condition in it. So, if you had two conditions inside your if statement, you'd have to count both. Here's an example of that:

function insert_default_value($mixed)          // 1
{
    if (!is_string($mixed) || empty($mixed)) { // 2,3
        $mixed = 'value';
    }

    return $mixed;
}

As you can see, we added a is_string before the empty check in our if statement. This means that we should count our if statement twice. This brings the cyclomatic complexity of our function to 3.

What's a good cyclomatic complexity value?

Alright, so you now have a better idea of what cyclomatic complexity is and how to calculate it. But this doesn't answer everything. You're still asking yourself, "How do I know if my function is too complex? What cyclomatic complexity value will tell me that?"

As a general rule, if you have a cyclomatic complexity value between 1 and 4, your code isn't that complex. We don't tend to think of code within that range as complex either. Most small functions of a dozen lines of code or less fit within that range.

A cyclomatic complexity value between 5 and 7 is when things start unravelling. When your code is in that range, its complexity becomes noticeable. You can already start looking at ways to reduce complexity. (We'll see what you can do to reduce complexity later in the article.)

But what if your code's cyclomatic complexity is even higher? Well at that point, you're now well into the "complex code" territory. A value between 8 and 10 is often the upper limit before code analysis tools will start warning you. So, if your code has a cyclomatic complexity value over 10, you shouldn't hesitate to try and fix it right away.

Issues with cyclomatic complexity

We already discussed the role of mathematics in cyclomatic complexity. If you love math, that's great. But it's not that intuitive if you're not familiar with mathematical graphs.

That said, there are two conceptual problems with cyclomatic complexity. Unlike the issue with mathematics, these two issues are quite important. That's because they affect the usefulness of cyclomatic complexity as a metric.

Not every statement is equal

The first one is that cyclomatic complexity considers all if, while, for and case statements as identical. But, in practice, this isn't the case. For example, let's look at a for loop compared to an if condition.

With a for loop, the path through it is always the same. It doesn't matter if you loop through it once or 10,000 times. It's always the same code that gets processed over and over.

This isn't the case with an if condition. It isn't linear like a for loop. (It's more like a fork in a road.) The path through your code will change depending on whether that if condition is true or false.

These alternative paths through your code have a larger effect on its complexity than a for loop. All the more so if your if conditions contain a lot of code. In those situations, the difference between your if condition being true or false can be significant.

Nesting

The other problem with cyclomatic complexity is that it doesn't account for nesting. For example, let's imagine that you had code with three nested for loops. Well, cyclomatic complexity considers them as complex as if they were one after the other.

But we've all seen nested for loops before. They don't feel as complex as a linear succession of for loops. In fact, they more often than not feel more complex.

This is due in part to the cognitive complexity of nested code. Nested code is harder to understand. It's something that a complexity measurement should take into consideration.

After all, we're the ones who are going to debug this code. We should be able to understand what it does. If we can't, it doesn't matter whether it's complex or not.

Complex vs complicated

The idea that code feels complex or is harder to understand is worth discussing. That's because there's a term that we use to describe that type code: complicated. It's also common to think that complex and complicated mean the same thing.

But that's not quite the case. We use these two terms to describe two different things in our code. The confusion comes from the fact that our code is often both complex and complicated.

So far, we've only discussed the meaning of complex. When we say that code is complex, we're talking about its level of complexity. It's code that has a cyclomatic complexity value. (Or a high value in another measurement method.) It's also something that's measurable.

Defining complicated code

But, when we say that code is complicated, it doesn't have anything to do with complexity. It has to do with the psychological complexity that we talked about with nesting. It's the answer to the question, "Is your code hard to understand?"

If the answer is "yes" then it's complicated. Otherwise, it's not complicated. But whatever the answer may be, it's still subjective.

Code that's complicated for you might not be for someone else. And the opposite is true as well. Code that isn't complicated for you might be complicated for someone else. (Or even your future self!)

This also means that code that was once complicated can become straightforward. (And vice versa!) If you take the time that you need, you can figure out how complicated code works. At that point, it isn't complicated anymore.

But that'll never be the case with complex code. That's because, when we say that code is complex, we base that on a measurement. And that measurement will never change as long as that code stays the same.

What makes code complex and complicated?

Now, let's talk about why the two terms get confused. If you think about what makes code complex, it's the number of statements in it. (Well, that's the simple way to look at it.) The more statements there are, the higher the cyclomatic complexity will be.

But code that has a lot of statements in it isn't just complex. There's also more going on. It's harder to keep track of everything that's going on. (Even more so if a lot of the statements are nested.)

That's what makes complex code harder to understand. It's also why it's common to think that the two terms mean the same thing. But, as we just saw, that's not the case.

In fact, your code can be complicated without being complex. For example, using poor variable names is a way to make your code complicated without making it complex. It's also possible for complex code to not be complicated as well.

NPATH

So this gives us a better understanding of what complicated code means. Now, we can move on and discuss another way to measure the complexity of a piece of code. We call this measurement method NPATH.

Unlike cyclomatic complexity, NPATH isn't as well known by developers. There's no Wikipedia page for it. (gasp) You have to read the paper on it if you want to learn about it. (Or keep reading this article!)

The paper explains the shortcomings of cyclomatic complexity. Some of which we saw earlier. It then proposes NPATH as an alternative measurement method.

NPATH explained

The essence of NPATH is what the paper calls "acyclic execution path". This is another fancy technical term that sounds complicated. But it's quite simple. It just means "unique path through your code".

This is something that's pretty easy to visualize with an example. So let's go back to our earlier example with the insert_default_value function. Here's the code for it again:

function insert_default_value($mixed)
{
    if (empty($mixed)) {
        $mixed = 'value';
    }

    return $mixed;
}

So how many unique paths are there through the insert_default_value function? The answer is two. One unique path is when mixed is empty, and the other is when it's not.

But that was just the first iteration of our insert_default_value function. We also updated it to use the is_string function as well as the empty check. Let's do the same thing for it as well.

function insert_default_value($mixed)
{
    if (!is_string($mixed) || empty($mixed)) {
        $mixed = 'value';
    }

    return $mixed;
}

With this change, there are now three unique paths through our insert_default_value function. So adding this condition only added one extra path to it. In case you're wondering, these three paths are:

When mixed isn't a string. (PHP won't continue evaluating the conditional when that happens. You can read more about it here.)
When mixed is a string, but it's empty.
When mixed is a string, but it's not empty.

Adding more complexity

Ok, so this wasn't too hard to visualize so far! In fact, you might have noticed that the NPATH values that we calculated were the same as the ones that we calculated with cyclomatic complexity. That's because, when functions are that small, both measurement methods are about the same.

But let's make things a bit more complex now. Let's imagine that we have an interface that can convert an object to a string. We'll call it the ToStringInterface interface.

function insert_default_value($mixed)
{
    if ($mixed instanceof ToStringInterface) {
        $mixed = $mixed-&gt;to_string();
    }

    if (!is_string($mixed) || empty($mixed)) {
        $mixed = 'value';
    }

    return $mixed;
}

Once more, we updated our insert_default_value function to use this interface. We start by checking if mixed implements it using the instanceof operator. If it does, we call the to_string method and assign the value it returns to mixed. The rest of the insert_default_value function is the same.

So what about now? Can you see how many unique paths there are through the insert_default_value function? The answer is six. Yes, we doubled the number of paths through our code. (Yikes!)

Statements are multiplicative

That's because, with NPATH, adding a new statement like this is multiplicative. That means that to get the total number of paths, we have to multiply the number of paths through the two if conditions together. We already know how many paths there are through each if condition because of our earlier examples.

The first if condition has two possible paths. It's whether mixed implements the ToStringInterface interface or not. And we saw before that the second if condition has three possible paths. So the total number of paths is 2 * 3 = 6.

This is also where NPATH and cyclomatic complexity diverge. This code only increased the cyclomatic complexity of our function by one. But having a cyclomatic complexity of four is still excellent. However, with NPATH, we can already see how much impact adding one more if conditions can have.

Large functions or methods are dangerous

The point of this example was to show that having a lot of conditionals in your function or method is dangerous. If we added a third conditional to our earlier example, you'd at least double your number of unique paths again. That means, that we'd have at least twelve unique paths through our code.

But how often do we code we just three conditionals? Not that often! Most of the time, we can write functions or methods with a dozen or more conditionals in them. If you had a dozen conditionals in your code, it would have 4096 (2¹²) unique paths! (gasp)

Now, a function or method with twelve unique paths is starting to get complicated. You can still visualize those twelve unique paths. It might just require that you stare at the code for a little while longer than usual.

That said, with 4096 unique paths, that's impossible. (Well, that's unless you have some sort of superhuman ability! But, for us, mortals it's impossible.) Your code is now something beyond complicated. And it didn't take many statements to get there.

How many unique paths should your code have?

This brings us to the obvious question, "How many unique paths is too many?" We know that 4096 is too many. But twelve is still quite reasonable if a bit on the complicated side.

Code analysis tools tend to warn you at 200 unique paths. That's still quite a lot. Most of us can't visualize that many unique paths.

But, again, that's subjective. It depends on the code or the person reading. That said, it's a safe bet to say that about 50 is a much more reasonable number of unique paths to have.

Managing complexity in our code

So how do we get from a function or method that has 4096 unique paths to one that has around 50? The answer most of the time is to break your large function or method into smaller ones. For example, let's take our function or method with 4096 unique paths.

Now, let's imagine that we broke that function or method in two. If we did that, it would have only six conditionals. (Six! Ha! Ha! Ha!) How many unique paths would there be through that our function or method now?

Well, we'd now only have 64 (2⁶) different unique paths in our function or method. That's a drastic reduction in complexity! And that's why breaking up a function or method is often the only thing that you need to do to reduce its complexity.

How to break up functions or methods into smaller ones

In practice, it's pretty rare that we can just split a function or method in two right down the middle. What will happen most of the time is that you'll only have small blocks of code that you can extract. So one function or method might become 3-4 functions or methods. The question then becomes what code is good to extract into a separate method or function.

Code that belongs together

The easiest code to spot is code that logically belongs together. For example, let's imagine that you have a function or method where some of the code validates a date string. It could look something like this:

function create_reminder($name, $date = '') 
{
    // ...

    $date_format = 'Y-m-d H:i:s';
    $formatted_date = DateTime::createFromFormat($date_format, $date);

    if (!empty($date) &amp;&amp; (!$formatted_date || $formatted_date-&gt;format($date_format) != $date)) {
        throw new InvalidArgumentException();
    }

    // ...
}

The create_reminder function has an optional date parameter. If we have a date, we want to ensure that it follows the Y-m-d H:i:s format. (You can find details on date formats here.) Otherwise, we throw an InvalidArgumentException.

We do this by creating a DateTime object using the createFromFormat static method. It's a static factory method that creates a DateTime object by parsing a time using a specific format string. If it can't create a DateTime object using the given format string and time, it returns false.

The conditional first checks if date is empty or not. Only if it's not empty do we use the DateTime object that we created. We first check if it's false and then we compare if our formattedDate matches our date.

We do that by using the format method. It converts our DateTime object to a string matching the given format. If the string returned by the format method matches our date string, we know it was correctly formatted.

Extracting the code

While we can't see the rest of the create_reminder function, it's not relevant here. We can see from what we have that this code is there to validate the date argument. And this is what we want to extract into its function.

function create_reminder($name, $date = '') 
{
    // ...

    if (!empty($date) &amp;&amp; !is_reminder_date_valid($date)) {
        throw new InvalidArgumentException();
    }

    // ...
}

function is_reminder_date_valid($date)
{
    $date_format = 'Y-m-d H:i:s';
    $formatted_date = \DateTime::createFromFormat($date_format, $date);

    return $formatted_date &amp;&amp; $formatted_date-&gt;format($date_format) === $date;
}

As you can see above, we moved everything related to the validation of the date to the is_reminder_date_valid function. This function creates ourformattedDate DateTime object using the dateFormat variable. We then do the check to see if formattedDate is false and if the output from the format method is identical to the given date.

In practice, this only removed one check from our conditional. This means that the cyclomatic complexity value of our create_reminder function would also go down by one. You could also have moved the empty check into the is_reminder_date_valid function and then it would have reduced it by two.

But let's keep the code that we have already. Now, reducing the complexity of method by one might seem insignificant. That said, it can have quite an impact due to the multiplicative nature of NPATH.

Let's imagine that our create_reminder function had two other if statements with a single condition in them. This would mean that our create_reminder function had 2 * 2 * 4 = 16 unique paths. (This is similar to our earlier example.) With our new if statement using the is_reminder_date_valid function, we'd have 2 * 2 * 3 = 12 unique paths.

That's a reduction of 25% in the total number of unique paths in your code. So it's not that insignificant in practice. That's why you should never think that extracting code for even one conditional statement is a waste of time. It's always worth it.

Large conditional statements

As we saw in the previous example, removing even one condition in an if statement can have a significant impact. The natural progression of this is to move entire conditional blocks into their functions or methods. This makes a lot of sense if the entire condition block is just to validate one thing.

function send_response(array $response)
{
    if (empty($response['headers']) || !is_array($response['headers']) || empty($response['headers']['status'])) {
        throw new \InvalidArgumentException();
    }

    // ...
}

Here's an example using a fictional send_response function. The function starts with a large if statement containing three conditionals. They're there to ensure that the response array contains a status header inside the headers subarray.

This type of conditional pattern is widespread with multi-dimensional arrays like this one. But it's also something that you'll use a lot when you use instanceof to check the type of a variable. In all those cases, you have to validate the type and structure of the variable before interacting with it.

function send_response(array $response)
{
    if (!response_has_status_header($response)) {
        throw new \InvalidArgumentException();
    }

    // ...
}

function response_has_status_header(array $response)
{
    return !empty($response['headers']) &amp;&amp; is_array($response['headers']) &amp;&amp; !empty($response['headers']['status']);
}

So to reduce the complexity of the send_response function, we created the response_has_status_header function. The response_has_status_header function contains the logical inverse of our previous condition. That's because we want the function to return true if there's a status header. The previous condition returned true if there wasn't one.

Aren't we just hiding the problem?

So this is a question you might have after seen how we break up large functions or methods into smaller ones. After all, the only thing that we've done is move code from one function or method to another. How can doing that reduce the complexity of your code?

That's because what we've seen is how to evaluate complexity within the scope of a function or method. We're not trying to evaluate the complexity of the software as a whole. That said, there's a correlation between the two. (That's why a lot of tools only analyze function or method complexity.)

So yes, simply moving code to a separate function or method can have a positive effect. You're not hiding the problem by doing that. But this only applies to code that's complex, not code that's complicated.

If your code was complicated, moving some of it to another function or method won't make it less so. (Well, that's unless what made it complicated was the size of the function or method!) Instead, you'd have to focus on fixing the things that made your code hard to understand in the first place. (That's a topic for another article!)

Combining conditionals together

While breaking functions or methods into smaller ones does fix most issues with complexity, it's not the only solution either. There's one other way to reduce complexity that's worth talking about. That's combining conditionals together.

function insert_default_value($mixed)
{
    if ($mixed instanceof ToStringInterface) {
        $mixed = $mixed-&gt;to_string();
    }

    if (!is_string($mixed) || empty($mixed)) {
        $mixed = 'value';
    }

    return $mixed;
}

Here's our insert_default_value function that we were working with earlier. As we saw, this function had an NPATH value of six. Now, let's imagine that the to_string method can never return an empty string.

This means that we don't need to have two separate if statements. Of course, we could keep them as is anyways. But what would happen if we changed our insert_default_value function to this:

function insert_default_value($mixed)
{
    if ($mixed instanceof ToStringInterface) {
        $mixed = $mixed-&gt;to_string();
    } elseif (!is_string($mixed) || empty($mixed)) {
        $mixed = 'value';
    }

    return $mixed;
}

If we combined our two if statements using an elseif statement, the NPATH value of the function goes from six to four. That's a 33% drop in the number of paths in our code. That's quite significant!

This happened because we added one more path to our three paths from earlier. And then we removed the two paths if statement that we had initially. So our NPATH calculation went from 2 * 3 = 6 to just 4.

Tools

While showing you how to calculate cyclomatic complexity and NPATH values is nice, it's not that practical. Most of us aren't going to go back through your code and do this for every function and method that we have already. You need tools to scan all your code and find the functions and methods with high complexity values for you.

Command-line tools

The first set of tools that we'll look at are command-line tools. These tools are a good starting point since they're free and you can use them on your development machine. PHP has two popular command-line tools that can analyze the complexity of your code: PHP code sniffer and PHP mess dectector.

PHP code sniffer is a tool for enforcing specific coding standards throughout out your code. Its main purpose isn't to manage the complexity of your code. That said, it does allow you to enforce that your functions or methods be below a specific cyclomatic complexity value. Unfortunately, it doesn't support NPATH as a complexity measuring method.

Unlike PHP code sniffer, PHP mess detector is a tool that whose purpose is to help you detect problems with your code. It offers support for both cyclomatic complexity and NPATH measurement methods. It also has a lot of rules to help make your code less complicated on top of less complex.

In practice, you should consider using both tools in your projects. But that might be a bit overwhelming if you haven't used either tool before. So, if you had to pick one, it would be PHP mess detector. It's the better choice for the task of evaluating the complexity of your code.

Code quality services

If you work in a team, using a command line tool might not be enough for you. You might want a more automated way to check and enforce low complexity in everyone's code. In that scenario, you might want to use a code quality service instead of a command-line tool.

Code quality services work by connecting to your git repository. Using that connection, they analyze your code each time that there's a commit or a new pull request. If there's an issue, they alert you via your chosen communication method. They also support status messages for GitHub and other git repository hosting services.

In terms of choice, PHP has a bit more of a limited selection of code quality services. The big three to choose from are Codacity,
Code Climate and Scrutinizer. All three are pretty much the same in terms of features.

The big difference between them is the price. They all offer free integrations for open source projects. But both Codacity and Code Climate charge per user per month which can make them quite pricey. Scrutinizer only charges a flat price per month.

Complexity isn't that complex

So this took us a little while, but we've made it through! Complexity is a topic that can be quite intimidating to developers. But that's because of the theory and the language surrounding the concept. They make it seem more complicated than it is in practice.

The truth is that managing software complexity is almost only about the size of your functions and methods. The mathematics behind it is just there as a way to quantify the effect of the size of your function or method. But it's not necessary for you to be able to do that to reduce complexity in your code.

Just focus on keeping your functions and methods small. If you see that they're getting large, find a way to break them into smaller ones. That's all that there is to it.

How to autowire a standalone Symfony console application

Carl Alexander — Thu, 10 Dec 2020 07:34:42 +0000

Working with the Symfony console component has always been a delightful experience. It makes it super easy to build a console application. You might need one while working with a framework. (Like Symfony or Laravel) Or you might just need to build a standalone console application.

That said, there are differences between building a standalone console application and building one with a framework. The biggest one is the use of dependency injection. Most standalone Symfony console applications that you can find out there don't use it.

That's a shame because the Symfony dependency injection component is full of awesome features. For the Ymir console application, I decided to look at how to build a console application using it. It's made building console applications even better.

A quick overview of the Symfony dependency injection component

Let's take a brief look at how to use the Symfony dependency injection component before integrating it. Central to the component is the service container. To build the service container, you need to use the ContainerBuilder class.

Now, you can manually build the container by defining parameters and services yourself. That said, it's much more common to use the Symfony config component to do it. The component lets you use YAML (with the help of the YAML component, XML or plain PHP files to configure the container.

This is what we're trying to do in this article. We want to configure a dependency injection container using a YAML file. (Feel free to use the file type that you prefer!) And then we want to compile the container and start the application using it.

$container->compile();

$container->get(Application::class)->run();

Above is all the code that you'd need to start the console application. No need to add any commands or deal with any dependencies. The configured container would have everything wired and ready to go for you.

Composer dependencies

With this small intro out of the way, Let's start with Composer dependencies that we'll need for this console application. We've mentioned them all already.

{
    "require": {
        "symfony/config": "^4.4",
        "symfony/console": "^4.4",
        "symfony/dependency-injection": "^4.4",
        "symfony/yaml": "^4.4"
    }
}

Above is the relevant section of the composer.json file for these dependencies. We need four Symfony components. These are the config, console, dependency injection and YAML components.

As mentioned earlier, the YAML component is optional. If you want to use PHP or XML to define your services, you don't need it. But for this article, we will use YAML for the services configuration so the dependency is necessary.

Another thing is that we're going to use version 4.4 of the Symfony components. This is current long-term support version of Symfony. So the code that you'll see will be good until the end of 2023. (And possibly longer.)

Creating the executable

Once the dependencies added and downloaded, we can start working on the console application. The primary interaction point with it is an executable file. Below is the base executable file that we're going to use for our console application:

#!/usr/bin/env php
<?php

require __DIR__.'/vendor/autoload.php';

Our PHP script starts with #! which is known as a hashbang. A hashbang tells a Unix-like operating system that it should interpret a text file as an executable file. (You also need to make it executable using chmod +x.) Following the hashbang is the interpreter that we want Unix to use.

Here, we want that interpreter to be PHP. We could use /usr/bin/php, but instead we used /usr/bin/env php. The reason to use env is that the script will not work if PHP isn't in the /usr/bin directory. env will search for the php executable and then launch it.

env is also useful if you have multiple PHP interpreters installed. This is especially common in local development. In that scenario, env will always pick the default PHP interpreter that you've chosen.

After the hashbang, the rest of our executable looks like a regular PHP script. We have the <?php opening tag. We then require the autoload file generated by Composer.

Adding the container

Now that we have our base executable, the next step is to add the dependency injection container. We want to configure and compile the container in the executable before running the console application. Let's look at what that looks like.

#!/usr/bin/env php
<?php

use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;

require __DIR__.'/vendor/autoload.php';

$container = new ContainerBuilder();

$loader = new YamlFileLoader($container, new FileLocator());
$loader->load(__DIR__.'/config/services.yml');

$container->compile();

We first start by instantiating a ContainerBuilder object. We then use that ContainerBuilder object to create a YamlFileLoader object. This is the configuration loader that we're going to use to configure our dependency injection container.

The YamlFileLoader object will load the services.yml file found in the config directory. The directory and file names are a personal choice. You can name the YAML file whatever you want and put it wherever you want really.

After loading it, we call the compiler method. This compiles the ContainerBuilder object and turns it into a Container object. You cannot use the container until you've done this.

Adding the base dependency injection container configuration file

Now, you could also load multiple configuration files if you wanted. But for this article, we're just going to use services.yml. Here's what it contains so far.

services:
  _defaults:
    autowire: true

The _defaults section is where you define the default configuration options for the services in your container. The most important one is autowire which you want to set to true. This is what turns on the amazing autowiring feature.

When autowire is true, the container will take over the handling of the dependencies for your services. It'll read the type hints of the constructor of each service. It'll then pass it the right dependencies when it creates the object the first time. (It's a really magical thing!)

Creating the Application class

Now that we have our compiled Container object, we can move on to our base Application class. You can see it below extending the Symfony Application class. We renamed it to BaseApplication to prevent a naming conflict.

namespace Console;

use Symfony\Component\Console\Application as BaseApplication;

class Application extends BaseApplication
{
    // ...
}

Empty like this, a console application doesn't do much. If you ran the list command for it, you'd get this:

There are only two available commands: help and list. This is how all Symfony console applications start out with. So what we really need to do now is add commands.

Adding commands to the application

Adding commands to an application is straightforward. All that you have to do is call the add method with the Symfony Command object you want to add. In our Application class, this could look something like this:

namespace Console;

use Symfony\Component\Console\Application as BaseApplication;

class Application extends BaseApplication
{
    /**
     * Constructor.
     */
    public function __construct(array $commands = [])
    {
        foreach ($commands as $command) {
            $this->add($command);
        }
    }
}

As you can see above, we added a constructor to the Application class. The constructor has a single parameter called commands. We use it to pass an array of Command objects to the constructor. We then loop through each one and add them using the add method.

Right now, we'd have to supply that array of Command objects to the constructor ourselves. But what we really want is for the dependency injection container to handle all that for us. It should find all the Command objects and pass them to the Application constructor.

Creating a service tag for command objects

To do that, we're going to use a service tag to identify all our Command objects. We can do that easily using the _instanceof option. Here's what it looks like in the services.yml file.

services:
  _defaults:
    autowire: true

  _instanceof:
    Symfony\Component\Console\Command\Command:
      tags: ['command']

We added the _instanceof section below the _default one. Under that section, you want to add the fully qualified name of the class or interface that we want to add a tag to. For this, we want to use the fully qualified of the Symfony Command class because it doesn't have an interface. That fully qualified name is Symfony\Component\Console\Command\Command.

Below that, we have the tags that we want all the Symfony Command objects to have. We just have one for this. It's command.

Using the service tag

Next, we need to configure the dependency injection container. Right now, it doesn't know that we want it to pass all the Command objects to the Application class constructor. To tell it to use our service tag, we have to modify the services.yml file like so:

services:
  _defaults:
    autowire: true

  _instanceof:
    Symfony\Component\Console\Command\Command:
      tags: ['command']

  Console\Application:
    public: true
    arguments:
      - !tagged command

Above you can see that we added the fully qualified name of the Application class as a new section. Below, we added the arguments section which lets you define the arguments to pass to a class constructor. We then used !tagged command as the first argument.

At this point, if you try to run your console application, you'll get an error like this:

PHP Fatal error:  Uncaught TypeError: Argument 1 passed to Console\Application::__construct() must be of the type array, object given

That's because the dependency injection container doesn't pass an array to our Application class constructor. It passes an object implementing the Traversable interface. This is a built-in PHP interface that lets an object work with a foreach loop.

namespace Console;

use Symfony\Component\Console\Application as BaseApplication;

class Application extends BaseApplication
{
    /**
     * Constructor.
     */
    public function __construct(iterable $commands = [])
    {
        foreach ($commands as $command) {
            $this->add($command);
        }
    }
}

To solve this issue, we need to change the type hint of the Application class constructor. If you want, you can use the Traversable interface. A better option is the iterable pseudo-type which is what the code above uses. But regardless of the one you use, once you update the constructor, the error will be gone.

Adding the application to the executable

At this point, you have everything that you need to run a console application using the dependency injection container. We just need to update the executable so we get the Application object from the container. You can see that below.

#!/usr/bin/env php
<?php

use Console\Application;
use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;

require __DIR__.'/vendor/autoload.php';

$container = new ContainerBuilder();

$loader = new YamlFileLoader($container, new FileLocator());
$loader->load(__DIR__.'/config/services.yml');

$container->compile();

exit($container->get(Application::class)->run());

At the top, we added the use statement to import the Application class. But really, what we care about at the bottom. It's the call to the exit function.

The exit function just terminated the PHP script using the given status. The status just comes from getting the Application object from the container. And then we call the run method which runs the console application and terminates.

To see a fully working version of a console application using this technique, I invite you to look at the code of the Ymir console application on GitHub.

Source