PHP at Scale #6

Welcome to the sixth edition of PHP at Scale. I am diving deep into the principles, best practices and practical lessons learned from scaling PHP projects — not only performance-wise but also code quality and maintainability.

🎉 “New Year, new me”, right? I hope you were able to take a bit of time off, and are now back to work with some interesting resolutions and/or plans.

For me, the start of the year is quite busy, so I will unfortunately keep this release rather short. I am actively working on some intriguing topics to share in the upcoming months, but they are not yet ready to be released.

This time, I would like to explore the topic of documentation. Documentation is quite tricky and probably annoying for many people, but bear with me! I’ll do my best to make it as practical as possible.

Documenting Architecture Decisions

If you do not have any documentation, ADR is the place to start in my opinion. You can easily take a lightweight approach. There are many ready-to-be-used templates, and you can easily find very simple ones. Choose one that works for you, your project and your team. Next, store it somewhere easy to access — both for reading/searching and writing. I personally prefer to have them in git, in the same repository as the project, but I noticed some articles mention Confluence or other similar tools. Whatever works for you! I guess teams that are heavily using Notion could use it for ADRs too. I would be against introducing any specific tool. Just make it easy, if you make it hard, no one will write and read them!

Visualising ADRs

As you grow the product, you might hit a problem with browsing the ADRs. I don’t think you need anything like this from the beginning, but it is good to know that you have such an option :) Structurizr is actually a nice tool to know, as it allows visualising not only ADRs but also other docs, especially based on the C4 model.

How to define and enforce a code structure in layered architecture

What I dislike about documentation, is that you need to always remember about it when you do or review some changes. At least for technical/architectural documentation. To efficiently adhere to documentation, you usually require someone who is a guardian of it and checks if it is up-to-date and applied in all the changes. There are projects where we have such guardians, they like the role, and the docs we have on Confluence are great, but this would not work in other projects. So every time you document something, it’s a good idea to check if adherence to such rules can be checked automatically. And this is why we use deptrac in our projects. A documentation is also created, in this case in the form of an ADR. But next to this, the checks are automated with deptrac, to ensure no false relations slip through our code review :)

Documenting Software Architecture

Select the right tool for your problem. There are many approaches and tools you can take to document software architecture. I find this article helpful in terms of getting a good understanding of the different solutions that could help you.

This is, of course, not a full list, but it covers at least a couple of approaches that are good to know.

And at this point you might scream “Wait! UML?! Is this 1997 again or what?”. I actually have a project, where it works superbly. We have multiple teams, working on multiple systems that need to communicate with each other. Combined with PlantUML or MermaidJS, it allows us to quickly draft a sequence diagram during a call. It is easy to understand both by more experienced developers as well as juniors.

Event Storming remotely - tips and tricks

What I have noticed recently, is that we switched the approach to event storming a lot in recent years. We have an ongoing project, that we have worked on for years already. The approach of short sessions described by Radek works for us very well. We just gather to discuss a certain flow or a set of flows. We have a Miro board that gathers all those flows together. We sometimes need to get back to the discussion, and this board helps a lot.

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!