Static code analysis is a method of debugging by examining source code before a program is run. It's done by analyzing a set of code against a set (or multiple sets) of coding rules. Static code analysis and static analysis are often used interchangeably, along with source code analysis.

What is PHPStan?

One of the most popular static analysis tools for the PHP language right now is PHPStan:

PHPStan focuses on finding errors in your code without actually running it. It catches whole classes of bugs even before you write tests for the code. It moves PHP closer to compiled languages in the sense that the correctness of each line of the code can be checked before you run the actual line.

Find a problem and propose a solution

Why you should be worried about catching the \Throwable exception?

Lets start with a code example:

try {
    // do whatever you want
} catch (\Throwable $e) {
    // hide everything, even PHP errors
}

This is dangerous, due to the usage of the top-level exception interface \Throwable, which means that every other exception must implement this interface. PHP fatal errors, built-in and user-land exceptions will be caught in such cases. This is dangerous as it increases the maintenance cost, and potentially hides code issues from developers.

PHPStan for a rescue!

PHPStan's core concepts are:

• Abstract Syntax Tree,
• Scope,
• Type System,
• Trinary Logic,
• Reflection,
• Dependency Injection & Configuration.

I will not get into all details in this article, as our custom rule will base just on the AST:

Abstract Syntax Tree (AST) is the way analyzed source code is represented in the static analyzer so that it can be queried for useful information.

For more information about the PHPStan core concept, I recommend reading an official documentation.

New custom rule to prevent catching \Throwable interface

Writing custom rules for PHPStan will allow it to detect this bug-prone code part and force developers to write it in a better way, with more bullet-proof code.

First let's create a new class: DisallowCatchingThrowableExceptionRule, we need also to implement PHPStan\Rules\Rule interface:

<?php declare(strict_types=1);

namespace App;

use PhpParser\Node;
use PHPStan\Analyser\Scope;
use PHPStan\Rules\Rule;

class DisallowCatchingThrowableExceptionRule implements Rule
{
    public function getNodeType(): string
    {
        return '';
    }

    /**
     * @return string[]
     */
    public function processNode(Node $node, Scope $scope): array
    {
         return [];
    }
}

Our new rule will work on the PHPParser statements classes, and in fact, it will be two of those:

• PhpParser\Node\Stmt\TryCatch, related to try {} catch () {} code fragment,
• PhpParser\Node\Stmt\Catch_, related to catch () code fragment.

We now also need to change the value of the getNodeType() method, to point PHP parser that we will work on statement level.

<?php declare(strict_types=1);

namespace App;

use PhpParser\Node;
use PhpParser\Node\Stmt;
use PHPStan\Analyser\Scope;
use PHPStan\Rules\Rule;

class DisallowCatchingThrowableExceptionRule implements Rule
{
    public function getNodeType(): string
    {
        return Stmt::class;
    }

    /**
     * @return string[]
     */
    public function processNode(Node $node, Scope $scope): array
    {
        if ($node instanceof Stmt\TryCatch) {
            return [];
        }

        return [];
    }
}

When you inspect the object of Stmt\TryCatch, you will notice it contains the $catches variable, which is an array of nodes: Stmt\Catch_. Now we can check what class name was used in it and compare it against the name of the \Throwable interface!

    /**
     * @return string[]
     */
    public function processNode(Node $node, Scope $scope): array
    {
        if ($node instanceof Stmt\TryCatch) {
            foreach ($node->catches as $catch) {
                foreach ($catch->types as $type) {
                    // To compare object against string value, we need to cast it back to string,
                    // we can use toString() helper method for that.
                    if (\Throwable::class !== $type->toString()) {
                        continue;
                    }
                }
            }

            return [];
        }

        return [];
    }

Now we need to mark that try {} catch () {} statement as broken. To do that we should add a custom attribute on the $catch that was a match against the \Throwable interface:

    /**
     * @return string[]
     */
    public function processNode(Node $node, Scope $scope): array
    {
        if ($node instanceof Stmt\TryCatch) {
            foreach ($node->catches as $catch) {
                foreach ($catch->types as $type) {
                    if (\Throwable::class !== $type->toString()) {
                        continue;
                    }

                    // Name of the attribute should be unique one to prevent issues with other PHPStan rules
                    $catch->setAttribute('__THROWABLE_NODE_ATTRIBUTE__', 'You cannot catch the \Throwable exception');

                    // We already found a "broken" catch, no need for further checks
                    break 2;
                }
            }

            return [];
        }

        return [];
    }

We have marked the broken part of the code, but it's not yet reported by PHPStan. To do that, we need to check if any processed node contains our newly set attribute and if so return an array of errors.

    private const THROWABLE_NODE_ATTRIBUTE = '__THROWABLE_NODE_ATTRIBUTE__';

    /**
     * @return string[]
     */
    public function processNode(Node $node, Scope $scope): array
    {
        if ($node instanceof Stmt\TryCatch) {
            foreach ($node->catches as $catch) {
                foreach ($catch->types as $type) {
                    if (\Throwable::class !== $type->toString()) {
                        continue;
                    }

                    $catch->setAttribute(self::THROWABLE_NODE_ATTRIBUTE, 'You cannot catch the \Throwable exception');

                    break 2;
                }
            }

            return [];
        }

        if ($node instanceof Stmt\Catch_ && $node->hasAttribute(self::THROWABLE_NODE_ATTRIBUTE)) {
            return [$node->getAttribute(self::THROWABLE_NODE_ATTRIBUTE)];
        }

        return [];
    }

Last but not least, you need to declare the newly created rule in your phpstan.neon file:

rules:
    - App\DisallowCatchingThrowableExceptionRule

If everything goes well, on the next usage of PHPStan you will notice a new error reported if your code contains: catch (\Throwable $e):

$ vendor/bin/phpstan analyse some_file.php
Note: Using configuration file /srv/phpstan.neon.
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ------ ----------------------------------------------------------
  Line   some_file.php
 ------ ----------------------------------------------------------
  666    You cannot catch the \Throwable exception
 ------ ----------------------------------------------------------

Summary

From this article, you could learn the basics of static analysis in the PHP language and how you could start writing your own custom rules for PHPStan. For more details, I highly recommend reading official PHPStan documentation about custom rules development.

Ready to use class as a gist:

Easy to copy version of this rule can be found in this gist.

NIH (Not Invented Here) syndrome is often considered an opportunity to prove to ourselves that we can do the same thing, but better, faster, nicer, and more secure than the original. According to Wikipedia, we can summarize NIH syndrome as:

Not invented here (NIH) is the tendency to avoid using or buying products, research, standards, or knowledge from external origins. It is usually adopted by social, corporate, or institutional cultures. Research illustrates a strong bias against ideas from the outside.

Sometimes NIH is considered a shortcut of NIHS (Not invented here syndrome).

Buy vs build - the management problems

When deciding to either buy software or build it in-house, staff management must take care to not follow NIH syndrome. While it may not be obvious when looking from the perspective of staff and chief level management, NIHS is quite a big part of the build decision. Developers may want to prove that they can do the job well.

NIHS can lead to not only expensive, time-consuming tasks, but may require managing hidden costs like maintenance. Other hidden risks from build decisions that may show up in the future are Bus Factor and Technical Debt.

Pay vs create - person’s dilemma

Similar to staff+ management decisions problems about what to do (buy vs build), people also often reach a dilemma: pay someone else or do something on their own. That dilemma is not only limited to software development but also to research, standards, or knowledge that others may provide for a price. In software development, this problem is more visible, because programmers love to prove themselves.

The time spent on developing, improving, or maintaining the created software is not usually taken into account when validating the price someone else asks us to pay for getting something ready to use.

Not invented here < reinventing the wheel

The syndrome is often considered an alias for reinventing the wheel. Those two terms differ in many layers. The meaning of the first is threatened in a pejorative sense, while the second is more in an ameliorative sense.

As an example of NIH syndrome: developers create a new internal framework for the company, instead of grabbing the existing and well-tested solution available on the market.

Reinventing the wheel led the PHP community to create the Composer package manager, the JavaScript community created NPM, and later Yarn. A lot of awesome projects started by reinventing some tools from one community into another. The same goes for programming languages which adopt features from different languages to evolve.

Consider reinventing the wheel a positive version of NIH syndrome.

Should I be scared of NIH syndrome?

In the PHP community we usually say:

Every programmer must write, at least once in a life, his/her framework

While the tone is sarcastic, it also highlights an opportunity to learn something new, prove ourselves, and give back knowledge to the community. While being unaware of failing into that syndrome may be dangerous and lead to other problems like low Bus Factor scores and high Technical Debt, being aware of possible problems and issues allows us to follow reinventing the wheel.

Now you know the basics about what NIH syndrome is and how it can affect you, your team, or even the whole company. While it may lead to improving your skills, knowledge, and experience, it may cause you other problems if you’re not careful to avoid its trap.

If you want to learn more about the Bus Factor, check out this article:

While the title may sound quite extreme, a similar sentence was asked publicly by Michael McLay in 1994:

If Guido was hit by a bus? (Guido van Rossum is the creator of the Python language)

That question led to the creation of the Bus Factor, known also as bus problem, truck factor, lorry factor, or even lottery factor.

What is a “Bus Factor”?

While there are several slightly different definitions on the Web, we may summarize them as:

The Bus Factor is the total number of people who would need to be incapacitated, as by getting hit by a bus so that the project would be left for dead.

To make this more descriptive, the Bus Factor score is an estimation of people who are so vital to your project that without them it will stall. If those people disappeared from the project for any reason (like an "accident" or even taking holiday, got fired, or left the project), no one would be able to maintain the project.

The lowest possible Bus Factor score is just 1, which means that if one person leaves the project it will stall or die. From a more technical point of view, this could be considered a single point of failure within the project. A much larger Bus Factor score is preferable, but not always easy to achieve.

Author: https://xkcd.com/2347/

PHP Community problem

At end of 2021, the PHP community received the sad information that after 10 years of implementing innumerable bug fixes, features & maintaining PHP, one of the main contributors: Nikita Popov, decided to focus on working in a completely different language and community (Rust & LLVM), of which he had already been apart for a few years.

Similar to the history of the Python language, that decision showed the PHP language has a really big problem with such a low Bus Factor score. It put the future of the language that powers up ~78% of the Web in a dangerous position.

To improve the current state, people and companies working on PHP joined forces and started a new initiative: PHP Foundation.

The PHP Foundation is a non-profit organization whose mission is to ensure the long life and prosperity of the PHP language.

The first decision made by the foundation was to hire/sponsor new developers to work on PHP core components. That way they could start increasing the Bus Factor score to a safer level. This is one of many steps that need to be taken by the community to make PHP's future safe and stable.

Company problems

Plenty of companies I worked for, from startups to corporations, often were hit hard by the Bus Factor. Many of their teams (most of the time not intentionally) fell into NIH (Not Invented Here), which led to problems with maintenance, higher entry-level for newcomers, as more & more things were created by people who could leave the project at any moment. This has often led to high Technical Debt (which I will try to explain in a later post).

A low Bus Factor score is often part of the fast-growing time when only a few developers create most of the functionality that later becomes the base for an increasingly complex project. Most companies start big hiring plans during such growth, but that's not something that can increase the Bus Factor alone.

How to increase a low Bus Factor score?

Coaching sessions & pair programming

Each new member should have at least 30 minutes of a pair programming session with one of the senior people within the project she/he is joining. During such sessions, a less experienced person should do most of the coding, while the senior mentors, leads by example and suggests parts that may help to achieve the goal of the task.

Your Bus Factor person as a teacher

When you identify Bus Factor people, you should focus on how they can share the knowledge they aggregated during all those years in your project. Their knowledge is one of the biggest values for your team. Have them focus more on writing documentation, creating cheatsheets, doing internal presentations, and sharing knowledge in one-on-one sessions with teammates. Their focus on programming should be reduced.

Code Review Culture

While adoption of the Code Review Culture is done by teams to improve the code quality and the review process, the less obvious outcome is direct knowledge sharing between people in the project. Reviews must not be just like giving a stamp of approval. They should point out why something was done that way, not another, leading to constructive discussions between seniors & other teammates about what could be done differently, from the perspective of seniors. Reviews must lead to discussion.

Reducing project(s) complexity

Often the problem of fast-growing companies is fast-growing Technical Debt, which leads to a low Bus Factor score. One of the effective techniques is reducing the complexity of projects by splitting them into smaller, more dedicated ones. This leads to lower entry-level, faster adoption, and easier maintenance. All these points allow increasing the overall Bus Factor quite effectively. The biggest issue you must avoid during reducing the complexity of projects is to always involve teams (even small ones) in refactoring to avoid creating the very same problem in the new sub-project(s).

Team "shuffling"

This can be the most effective way of increasing the Bus Factor score, but it's also the most difficult and dangerous one. You need to deeply plan every possibility to prevent losing team morale. "Shuffling" should not be forced, but proposed to team members on a regular basis, like: once every two quarters; teammates cannot change teams too often as they will need to be onboarded like a newcomer. If well planned & executed, your teams will get much wider experience in different domains, sharing the knowledge learned while working with other teams.

Training budget

Planning training budgets for your developers can also increase the Bus Factor score as people will gather a wider range of experience, and expand your team to have more people in each seniority rank within your company hierarchy.

Summary

It’s not that easy, cheap, or quick to increase your team Bus Factor score. There are cases when you don't want (or even can't) easily increase that score, for example when the project contains sensitive data and you can't trust your new hires to start handling it. But now you know some of the basics that can help you prevent having your operations grind to a halt due to a "bus accident".

About what the book is?

It's a business novel, where fiction is used to point the reader to some of the business values, but unfortunately in my opinion it makes reading a bit harder. The story is about a newly promoted IT manager who struggles to learn how to evolve outdated approaches in a big company, starting from "nothing" with plenty of legacy projects to handle, into a full DevOps based approach, with agile & lean management technics.

From that book you will learn about:

• basics about Technical Debt,
• how unproductive meetings make morale lower,
• how "unexpected requests" can affect the work of everyone in the company,
• how a "small fix" on a production server can lead to a P1 issue for the whole weekend,
• that you probably know a person like one of the heroes of that story: Brent,
• how Bus Factor can stop all the work of the IT department,

For whom I would recommend it? For sure:

• everyone who starts her/his journey with IT,
• every developer or anyone else aspiring to become a Product Manager or Engineering Manager,
• programers or DevOps will find a lot of "memories" (good and bad as well) in that novel.

If you are interested to read more about Bus Factor, please check out this article: