Prepare your PHP Code for Static Analysis

#php #phpstan

Three years ago I got a new job as PHP developer, before that I called myself web developer because I build ReactJS, jQuery, CSS, HTML, … and PHP stuff for a web agency. So now I am a full-time PHP developer and I converted a non typed (no PHPDoc + no native types) project with ~ 10.000 classes into a project with ~ 90% type coverage. Here is what I have learned.

1. Write code with IDE autocompletion support.

If you have autocompletion in the IDE most likely the Static Analysis can understand the code as well.

Example:

bad:

->get('DB_Connection', true, false);

still bad:

->get(DB_Connection::class);

good:

getDbConnection(): DB_Connection

2. Magic in Code is bad for the long run!

Magic methods (__get, __set, …) for example can help to implement new stuff very fast, but the problem is nobody will understand it, you will have no autocompletion, no refactoring options, other developers will need more time to read and navigate in the code and in the end it will cost you much more time than you can save with it.

3. Break the spell on Magic Code …

… by explaining to everyone (Devs > IDE > Tools) what it does.

Example 1:

We use a simple Active Record Pattern, but we put all SQL stuff into the Factory classes, so that the Active Record class can be simple. (Example) But because of missing support for Generics we had no autocompletion without adding many dummy methods into the classes. So one of my first steps was to introduce a “PhpCsFixer” that automatically adds the missing methods of the parent class with the correct types via “@method”-comments into these classes.

Example 2:

Sometimes you can use more modern PHPDocs to explain the function. Take a look at the “array_first” function in the linked Post.

Example 3:

/**
 * Return an array which has the Property-Values of the given Objects as Values.
 *
 * @param object[] $ObjArray
 * @param string $PropertyName
 * @param null|string $KeyPropertyName if given uses this Property as key for the returned Array otherwise the keys from the
 * given array are used
 *
 * @throws Exception if no property with the given name was found
 *
 * @return array
 */
function propertyArray($ObjArray, $PropertyName, $KeyPropertyName = null): array {
    // init
    $PropertyArray = [];

    foreach ($ObjArray as $key => $Obj) {
        if (!\property_exists($Obj, $PropertyName)) {
            throw new Exception('No Property with Name ' . $PropertyName . ' in Object Found - Value');
        }

        $usedKey = $key;
        if ($KeyPropertyName) {
            if (!\property_exists($Obj, $KeyPropertyName)) {
                throw new Exception('No Property with Name ' . $PropertyName . ' in Object Found - Key');
            }
            $usedKey = $Obj->{$KeyPropertyName};
        }

        $PropertyArray[$usedKey] = $Obj->{$PropertyName};
    }

    return $PropertyArray;
}

Sometimes it’s hard to describe the specific output types, so here you need to extend the functions of your Static Code Analyze Tool, so that it knows what you are doing. ⇾ for example here you can find a solution for PHPStan ⇽ but there is still no support for the IDE and so maybe it’s not the best idea to use magic like that at all. And I am sure it’s more simple to use specific and simple methods instead: e.g. BillCollection->getBillDates()

4. Try to not use strings for the code.

Strings are simple and flexible, but they are also bad for the long run. Mostly strings are used because it looks like a simple solution, but often they are redundant, you will have typos everywhere and the IDE and/or Static Analysis can’t analyze them because it’s just text.

Example:

bad:

AjaxEditDate::generator($bill->bill_id, $bill->date, 'Bill', 'date');

“Bill” ⇾ is not needed here, we can call e.g. get_class($bill) in the “generator” method
“date” ⇾ is not needed here, we can fetch the property name from the class
“$bill->bill_id” ⇾ is not needed here, we can get the primary id value from the class

good:

AjaxEditDate::generator($bill, $bill->m()->date);

5. Automate stuff via git hook and check it via CI server.

Fixing bad code is only done if you disallow the same bad code for the future. With a pre-commit hook for git it’s simple to run these checks, but you need to check it again in the CI server because the developers can simply skip these checks.

Example:

I introduced a check for disallowing global variables (global $foo && $GLOBALS[‘foo’]) via “PHP_CodeSniffer”.

Links:

6. Use array shapes (or collections) if you need to return an array, please.

Array shapes are like arrays but with fixed keys, so that you can define the types of each key in the PHPDocs.

You will have autocompletion for the IDE + all other devs can see what the method will return + you will notice if you’re better retuning an object because it will be very hard to describe the output for complex data structures and Static Analysis can use and check the types.

Example:

/**
 * @return array{
 * missing: array<ShoppingCartLib::TAB_*,string>,
 * disabled: array<ShoppingCartLib::TAB_*,string>
 * }
 */
private static function getShoppingCartTabStatus(): array {
 ...
}