How to Choose a PHP API Framework

Alan and I provide API strategy for a software company who asked us whether they should use a PHP framework and, if so, which one would be best. They also wondered whether to invest in a commercial API gateway.

My thoughts on APIs and frameworks struck Alan as useful for any language and platform. Alan encouraged me to document my “philosophy of frameworks” here for anyone planning to develop web apps or APIs.

Why consider a framework?

As a general rule, it’s reasonable to externalize elements that are not critical to your business. If your company is a manufacturer, for example, you could outsource your delivery system—it’s not core to manufacturing. Likewise, with software, the core is your business logic, not the web server or a logging library or database.

This is where a framework comes in. The framework can handle rote tasks that are fairly common to all web applications and APIs, but not core to your business.

For example, the front controller pattern, where all requests pass through a central script, is very beneficial in a web framework. A front controller script ensures consistency by centralizing relevant code that runs on each request and takes the user to the right place. Without a front controller, the user would go directly to scripts such as news.php or login.php, which can lead to code duplication and errors.

Editor’s Note: For more detail on evaluating your need for a framework, see Does Our PHP API Need a Framework? A Q&A with Rob Allen.

Large or small framework?

I personally prefer relatively small third-party code libraries that you can mix and match. These are often called microframeworks.

Some developers prefer one large framework that does more. In the USA, the popular choice would be Laravel. In Europe, Symfony. If you write a Laravel app, you should do it the Laravel way, using their features. Your code is integrated into the full-stack framework, like a close partnership with a business.

If, however, you mix and match smaller components, you have more choices. You do more of the work, take more ownership, and retain more control. It’s lower risk, in my opinion, in the event that the framework is no longer updated or changes drastically, or if you change how you do things.

PHP microframework examples

Slim is a microframework that does the minimum amount of work related to building a web application in PHP: mostly routing and not a lot else. Disclosure: I am a lead developer of Slim, although there is no financial gain involved because, like the other frameworks mentioned here, Slim is free and open source.

Here’s a very simple overview of Slim. Slim provides a front controller so that all requests come into a single entry point. Then there’s a pipeline of modules of code (known as middleware) that runs on each request, which then dispatches to an action (this is the part you write) that generates a page for that particular request. Slim also provides error handling.

Slim is not concerned with other logic, such as how you render your page, database connectivity, login library, queuing system, and email. Those are not part of Slim. Something like Laravel has code for all that.

Another microframework worth looking at is Mezzio from Laminas, which evolved from Zend Framework. Mezzio is similar to Slim—perhaps slightly bigger—with a centralized configuration system that can be helpful. The pros and cons of each make it a toss-up to decide. (I’m on the Laminas steering committee.)

Laminas itself is a heavier, full-stack framework. Mezzio is lightweight, and where the future of Laminas is going. Mezzio will be easier for people to deal with long-term.

More about front controllers and routing for APIs

When you develop an API, the front controller pattern and routing become more important—and more complex—than for a traditional website.

For a normal website, you need only two methods: GET and POST. In an API, you also have PUT, PATCH, DELETE. Therefore, any given URL can have five operations against it. Each page needs a switch statement (PHP’s version of a case statement) to indicate which kind of request is being sent. Better yet, you can centralize that logic in the routing system of the framework.

Efficiency of frameworks vs. custom code

Do frameworks add overhead and inefficiency?

Even if you wrote a fully custom application without any third-party frameworks, you’d still need to write a front controller and routing code. You’d probably write code similar to the framework’s to get from the initial request to the response. Microframeworks such as Slim don’t add too much overhead compared to this.

Framework components do tend to add some overhead, however, because they are more generic than a completely custom application, but that overhead often happens even in our bespoke code because developers tend to generalize code toward wider usage than the immediate needs, just as frameworks do.

Frameworks encourage better practices

Although frameworks cannot force you to stay within their standards, they do encourage better practices. (I say “better” practices, not “best” practices.)

As one example of better practices in good frameworks: they encourage dependency injection, so that code in one class can’t interfere with code in another class. This way, when you modify code in one file, you’re less likely to affect another. This is incredibly beneficial as projects get bigger.

Dependency injection also helps separate the creation of an object and, later, the use of the object. Those two blocks of code are separate from each other, leading to clearer thinking about your code.

Do APIs require a “view” or presentation layer?

APIs most definitely have a presentation layer, which happens to be JSON. This presentation code layer should remain separate from the business processes of the API.

Do you need an API management gateway?

Consider an API management gateway when your API is business-to-public and may get a very high volume of requests. In that case, it could provide a good return on investment (ROI). If you expect a limited/controlled set of clients (e.g. qualified/limited partners), then a gateway is probably not worth the money.

Moving forward over time

A code base must move forward over time. This forward motion is an investment that must be paid for, or the code base falls to bits.

It’s similar to how physical properties and structures, such as bridges, must be maintained over time. The Forth Bridge in Scotland is a good example of continuous maintenance. Until modern coatings were developed in 2011, the bridge was continuously painted and repainted by a dedicated maintenance team.

Likewise, for software maintenance, you must spend a certain amount of time updating dependent libraries and improving your core code with the latest development practices. How we code now reduces the number of bugs that arise in the future.

Be aware that Javascript libraries change more quickly than PHP libraries. They can add risks, such as ending up with code that people don’t understand in the future.

A company’s core code and business competency will outlive third-party code libraries and coding styles. How can you make framework updates easier?

Separate framework functions from your critical business logic. For example, I would recommend keeping manufacturing logic separate from code that, say, displays the information on a web page or green screen. Code that calculates raw material requirements is separate from code that writes to the database. You should be able to change one without changing the other. This is called “separation of concerns,” another “better practice.”

Conclusion

Choosing an API framework is an important part of your API strategy. If you’d like help choosing the best path for your organization, let us know.