PHP at Scale #14
Welcome to the fourteenth 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.
If you’ve been working with mature PHP applications for a while, you’ve probably faced this situation more than once: you know exactly what needs to be refactored, you understand why it matters, and you’re ready to fix it. But then comes the hard part: convincing stakeholders who aren’t quite technical to approve the time and resources.
In fact, one of the most common questions I receive after my refactoring/rewriting talks is how to convince the business.
Today, I want to share practical strategies for bridging this gap. Not theoretical frameworks, but approaches I’ve seen work in real companies with real deadlines and real budget constraints.
—
—
The Technical Debt Metaphor - Using It Properly
The “technical debt” metaphor itself. We throw this term around constantly, and it often backfires when talking to non-technical stakeholders.
How to Explain Technical Debt to Executives
This article makes an excellent point: technical debt isn’t actually a technical problem. It’s a communication issue. When we say “technical debt” to business folks, they hear “the engineers want to rewrite code because they don’t like how it looks.” That’s not helpful.
I’ve had much better success when I frame it as a business decision that was made (often with good reason!) rather than a mistake that needs fixing. Did we skip writing tests to hit a critical launch date? That was a trade-off, not incompetence. Did we choose a quick-and-dirty implementation because market timing mattered more than perfect architecture? That’s called prioritization.
If You Want to Address Tech Debt, Quantify It First
This one gets into the fundamentals of actually measuring this stuff. The author breaks it down into three types of costs: maintenance time (how long it takes to work with the code), opportunity cost (what we’re not building because we’re fighting with legacy code), and human cost (developer frustration and turnover). I’ve seen teams lose senior developers because they were tired of fighting with poorly architected systems. That’s real money walking out the door.
We once lost a project because I assumed the business that came asking for refactoring understood the situation they were in. It turned out, they did not. After three weeks, they got frustrated with how long it would take (because we had to pay interest for 15 years of previous development shortcuts), and terminated the agreement. Providing some numbers and explanations would probably prevent this case.
Quantifying the Invisible - Metrics That Matter to Business
Okay, so we agree that we need to translate technical concerns into business language. But how do you actually do that? In my experience, you need metrics that business stakeholders already understand and care about.
The previous article already brought up some interesting things you can measure, but I personally think DORA metrics are a great idea. DORA metrics have become the industry standard for a good reason.
I’ve found it most useful for making business cases:
Lead Time for Changes — how long it takes to go from code commit to production. When this number is high, it means we’re slow to respond to market opportunities or customer issues. Business folks get this immediately — it’s about competitive advantage.
Change Failure Rate and Mean Time to Recover — how often do we have bugs after a deployment? How much does it cost to fix it, and how long does it take? Measuring this and showing it as numbers might be surprising to the business owners, and make it easier to make the decision to improve some parts of the software.
This article tries to provide a framework for how to translate the metrics into money and financial calculations. If you show a good Return on Investment for a refactoring task you suggest, it will be way easier for stakeholders to agree on such changes.
Calculating the ROI and the values might bring intriguing conclusions. Sometimes it will be clear that a refactor is required, sometimes it will show that it does not make sense. And sometimes… well, the decision is to drop a feature. Anyway, the discussion is always a good thing to have.
Speaking Their Language - Communication Strategies
Numbers are necessary, but they’re not sufficient. You also need to communicate in a way that resonates with your audience’s concerns and constraints.
I’ve learned to start every technical improvement proposal by connecting it to something the business already wants. Don’t lead with “our monolith needs to be broken into microservices.” Lead with “we’re currently blocked from shipping the new tenant features because making changes safely in the current architecture takes too long.”
Large-scale refactoring sponsorship series
This 14-part series is the most comprehensive guide I’ve found on getting refactoring sponsorship. Each post is 3-4 minutes, and the link takes you to the full series overview, where you can cherry-pick based on your needs.
I’d especially recommend:
Making the business case (Parts 1 & 2) - Step-by-step ROI calculations with real numbers.
5 Warning signals - How to use fear and urgency effectively with stakeholders.
Become a Business Partner - Moving from begging permission to partnership.
The series covers everything from finding time slots for refactoring to the Mikado Method for incremental delivery. It’s battle-tested advice from someone who’s fought these battles many times.
What a lot of people don’t understand is that these kinds of discussions are what you would call “sales”. There are many books and papers around this topic, from the very popular “How to Win Friends and Influence People”, through “Never Split the Difference: Negotiating as if Your Life Depended on It”, and finishing on “To Sell Is Human: The Surprising Truth About Persuading, Convincing, and Influencing Others”.
Each one offering a different view on the problem.
You can include your company's salesperson in the process if that’s possible, but I believe each of us should know the basics.
What the series emphasises is also important: don’t ask for permission to fix everything at once. Build trust by fixing one thing, showing the impact, then tackling the next.
I struggle to understand why so many teams try to sell technical improvements as all-or-nothing propositions. “We need six months to rewrite the authentication system”, which rarely gets approved. But “we can improve login performance by 50% and make password resets more reliable in the next sprint” often does. Once you’ve proven you can deliver on smaller improvements, bigger asks become easier.
Another lesson I’ve learned: show, don’t just tell. Before asking for approval on a big refactoring, do a small proof-of-concept. Spend a few hours creating a cleaner version of one problematic area. Measure the difference in test coverage, code complexity, and development time for new features. Then present that evidence.
I’ve seen countless situations where the business was against a change, but the developer kept pushing and finally came up with a demo, perfectly showcasing the benefits of what he suggested. In most cases, the idea was sold, and we could continue with the implementation. Nowadays, with the help of AI, you might be able to implement such MVP changes even more easily and faster; in fact, we already have a couple of such cases in our projects.
Another nice way of “smuggling” some changes is FedEx Days. We did it once, and the results were so good, the business is asking us when the next day will be ;)
I hope the above articles will help you a bit with your projects and will make your approach to refactoring more mature. Being able to choose which debt should be paid off first, what is the ROI of the change, and having tools to sell it to the stakeholders brings the “game” to a different level - trust me.
In 100% of the mature software I’ve worked with, we’ve had technical debt. That’s not a failure — that’s reality. The successful teams aren’t the ones with perfect code. They’re the ones who manage debt deliberately, pay it down strategically, and communicate about it honestly.
It is not about enforcing your decisions, just presenting them well, and sparking a good discussion. Trust and partnership are key. What is your next step? What part should be refactored, and how to sell it?
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!