A simple recipe for framework decoupling

Posted on by Matthias Noback

If you want to write applications that are maintainable in the long run, you have to decouple from your framework, ORM, HTTP client, etc. because your application will outlive all of them.

Three simple rules

To accomplish framework decoupling you only have to follow these simple rules:

  1. All services should get all their dependencies and configuration values injected as constructor arguments. When a dependency uses IO, you have to introduce an abstraction for it.
  2. Other types of objects shouldn't have service responsibilities.
  3. Contextual information should always be passed as method arguments.


Rule 1

Following rule 1 ensures that you'll never fetch a service ad hoc, e.g. by using Container::get(UserRepository::class). This is needed for framework decoupling because the global static facility that returns the service for you is by definition framework-specific. The same is true for fetching configuration values (e.g. Config::get('email.default_sender')).

Sometimes a dependency uses IO, that is, it talks to the database, the filesystem, etc. In that case you should introduce an abstraction for the dependency. If you depend on a concrete class, that class will work only with the specific library or framework that you're working with right now, so in order to stay decoupled you should use your own abstraction, combined with an implementation that uses your current library/framework.

Rule 2

Aside from services there will be several other types of objects like entities, value objects, domain events, and data transfer objects, all of which don't have service responsibilities. None of them should have service responsibilities, because that means they will either invoke services via some global static facility, or they need special framework/ORM-specific setup meaning they can't be used in isolation and won't survive a major framework upgrade or switch. An example of an object that doesn't follow rule 2 is an active record model, which may look like an entity, but is able to save itself, which is in fact a service responsibility.

Rule 3

Contextual information is usually derived from the current web request or the user's session, e.g. the ID of the user who is currently logged in. Instead of fetching this data whenever you need it (like Auth::getUser()->getId()) you should pass it from method to method as a regular argument.

Combined, rule 1, 2, and 3 ensure that for every method it's totally clear what it's doing, what data it needs, and on what service dependencies it relies to do its work. On top of that, none of the dependencies or method arguments will be framework or library-specific, meaning your application code will be effectively be decoupled from the framework.


If you ask me, these rules are very simple indeed, and they don't require a lot of extra work compared to tightly coupling everything to your project's current set of installed packages. So, why not follow them if you know that your project should still be up-to-date with current standards 3 years from now?

P.S. Following these rules gives you much more than framework decoupling: everything becomes testable in isolation, the tests are fully deterministic and therefore very stable, and they are really fast to run.

PHP framework decoupling
This website uses MailComments: you can send your comments to this post by email. Read more about MailComments, including suggestions for writing your comments (in HTML or Markdown).
Biczó Dezső
"you have to decouple from your framework, ORM, HTTP client, etc."

Do you have a good example of how to decouple from HTTP clients? I used to think (and rely on) PSR-18 for this but that kills async communications. HTTPlug also try/tried to be a middle ground between HTTP client implementations but that is not easy: https://github.com/php-http/guzzle6-adapter/issues/49
So what is your recommended approach to writing an HTTP client (ex.: Guzzle, Symfony HTTP client, etc) independent code in 2o2o (ex. an API client) but still supports async communication (promises)?
Oliver Mensah
I think this video of his will be useful, https://www.youtube.com/watch?v=Ri0AtbiShIw&t=1s
Biczó Dezső
Thanks Oliver, I watched the video, it also confirms that PSR-18 is the way to go, although as I described in my previous comment, that makes async communication impossible - even the HTTP client supports it (like Symfony's HTTP Client). So the conclusion is that if I want an HTTP client independent code at this moment then I should sacrifice the possibility of async communications in my API client, should not I?