Welcome to the third edition of PHP at Scale, I am diving deep into the principles, best practices, and practical lessons learned from the field of scaling PHP projects - not only performance-wise but also code quality and maintainability.
Last month, I focused on keeping our codebase up to date. This time, let’s focus on what day-to-day rules we can follow to improve our code.
Best PHP Code Review Practices
Code reviews should be a standard in your company if you strive to produce quality code. It can be tedious, but it is well worth the effort. It improves the code quality and serves as a great knowledge transfer tool, improving your team’s bus factor. In this article, I mention some of the best practices, but in general code review is a very broad topic, and each developer might have his own, unique approach. If you have your own tips or best practices, let me know! :)
When this article was published, I had some discussions, that nowadays, with all the tools and AI ― code review is a waste of time. I would say I partially agree with that comment. Each tool that automates a part of work should always be considered. I hope no one checks code formatting in code reviews ― that’s been done by a lot of tools for years. But I don’t think any of the tools available at the moment, can do a good check of variable names, some edge cases, etc. Also, as mentioned - code review is a great knowledge transfer tool.
The automation part - CI pipeline setup is a topic for a different newsletter release. Let me know if you are interested in it.
Solid PHP - SOLID principles in PHP
SOLID might be old, and there might have been some arguments about it in recent years and some alternative approaches. Yet, it is still one of the most popular articles on our blog.
What I like most about this article is that it covers both the basics written down many years ago, but it also extends into modern use of SOLID principles - how to apply the principles to API design. Or how to combine solid with modern frameworks (Symfony in our case).
Whether you consider SOLID a good idea or not, I think everyone should learn those principles and apply them depending on valid reasoning, not popular opinions. You might also apply just a part of it, that makes sense in your case. There is a huge difference between violating rules because of negligence, and because you knowingly chose to skip them for a good reason.
If you want to check some polemics against SOLID, this might be a good start.
Now back to my comments about SOLID. Suppose you read the polemics around the Open-Closed Principle and compare it to the API example given by Michal in his SOLID article, it becomes clear why I think it’s best to know SOLID, as well as the counterargument. A public API shouldn’t be changed too often!
CUPID was introduced as an alternative to SOLID, and this article introduces the principles. For me, the biggest downside is that it is way harder to say if what you’ve done is following the rules, or not. Anyway, it's always good to know them.
Automated testing is a great way to improve software quality. I don’t think you need to follow TDD or have nearly 100% coverage to benefit from the positive impact automated tests have on your system. A couple of things that I would like to stress here is that in my opinion:
Unit tests give the most value vs time required for writing and maintaining them.
By unit, you shouldn’t always consider just a class, units can be bigger (see talks by Jakub Nabrdalik).
I noticed that writing tests first (TDD) improves the code structure, as you need to make the parts easier to access for tests. Especially less experienced developers, introduce very strange approaches to add tests on badly designed code. By writing tests first, you think about the API of a class first, split it into smaller chunks and add interfaces and strategies.
You can introduce some simple rules in your team, for example ― Voters (part of Symfony Security component) should have 90+% coverage. Voters are a great example, as they are easy to test and have a big impact on the system. Such rule checks can also be automated in the CI :)
Notice something that might be improved when touching existing code? Fix it! Just make sure the fix won’t require refactoring 50% of the system ;)
There are some simple examples in the article. We tend to work with projects for multiple years, and such small day-to-day changes make a huge impact over several years.
Why is this newsletter for me?
If you are passionate about well-crafted software products and despise poor software design, this newsletter is for you! With a focus on mature PHP usage, best practices, and effective tools, you'll gain valuable insights and techniques to enhance your PHP projects and keep your skills up to date.
I hope this edition of PHP at Scale is informative and inspiring. I aim to provide the tools and knowledge you need to excel in your PHP development journey. As always, I welcome your feedback and suggestions for future topics. Stay tuned for more insights, tips, and best practices in our upcoming issues.
May thy software be mature!