Exakat 1.4.5 review

Exakat 1.4.5 brings two new reports, and a new analyzer. It also packs a lot of incremental updates. The reports are work-in-progress : the Manual report, which documents your code; and the Weekly report, which brings the community together to hunt for bugs. The new analyzer suggests some default value for argument, whenever possible. And the upgraded analysis includes not so obvious updates with empty methods, unused functions, $this being an array.

Empty functions

So, empty function, or methods, or closures, are just that : empty.

<?php
   function foo() {}
?>

On top of that, functions, or methods, that only include a static or global keyword are now considered empty. Also, if the function only return, with void or null : both are considered now empty functions.

<?php
   // One hard-working empty function
   function foo() {
     $a = 1;
     $b = $a + 1;
     return;
   }
?>

The above code is actually doing some work, but as it finally doesn’t return anything, it may be considered as empty. When the analysis runs on a method, it is a little more refined : it takes into account property usage.

Unused functions

Unused functions are very straightforward to find : nobody calls them.

<?php

// No 'foo()' calls, anywhere in the code. 
function foo() {}
?>

We could leave it at that, but here is a catch : what about recursive functions ? Those functions do have a call : an inner call.

<?php

// No 'foo()' calls, anywhere in the code. 
function foo($a) { 
  if ($a > 1) {
     foo($a - 1);
  }
}
?>

So, let’s look back to the original definition : unused functions are functions that are not called from outside.

And yet, appears another case : level 2 recursive functions. They call mutually each other.

<?php

// No 'foo()' nor 'bar()' calls, anywhere in the code. 
function foo() { bar(); }
function bar() { foo(); }
// Note : the code in the above functions may hold more than just a functioncall... 
?>

At that point, both foo and bar are calling each other. We need to check outside those two functions, if there is any call to one of the two functions. This will initiate the usage of both.

Could we go beyond and check Level 3? Level 4? Level n? Well, we could, and we should. The maximum level of any application would then be the number of distinct functions available in the code. That could make a lot of tests, with a declining return on investment : it probably takes some dedication to build a circle of ten functions, without calling any of them.

The current analysis only applies to functions, and not methods. Theoretically, the reasoning does apply, including mix and match of functions/methods calls. Though, methods are currently harder to handle, so this is not ready yet. We’ll tell you when.

$this is an array (sometimes)

$this is an object : it represents the current instance. And the current instance may also implement the ArrayAccess interface, or extends ArrayObject or SimpleXMLElement. While the first extension is a native PHP, the second one is related to simplexml extension.

In that configuration, $this may be used with the array syntax too.

<?php
class myClass extends ArrayObject{
    private $mediam = 0;
    
    function getMedian() {
        $this->median = intdiv(count($this) , 2);
        // Yes, this is valid syntax
        return $this[$this->median]; 
    }
}

$x = new myClass(range(10, 100));

print $x->getMedian();
?>

In PHP 4 (yes, 4), $this could be used as an array without any special extension or implementation. This is a well-kept secret, but objects and arrays were very similar at that age. This is not the case anymore, unless you’re still relying on PHP 4 code : after all, old style constructors are still encountered.

Now, Exakat reports wrong usage of $this with greater accuracy : it takes into account the classes. If you encounter other classes than support directly or indirectly this syntax, send us a note, so we’ll add it to the list.

The Manual report

The manual report is a new report : it is also a work in progress. Its aim is to document a piece of code with as much information as possible about the code. The current version features the following sections :

• The exception tree
• The constants list and their value
• The folders
• The dynamic expressions
• The error messages used
• The incoming variable list
• The session variables
• The email list

To extract this manual, run the following command :

php exakat.phar report -p <yourproject> -format Manual 

You may also use an optional -filename <filename> to give it a specific name. Otherwise, it will simply be <yourproject>.exakat.md, located as usual in the projects/<yourproject>/ folder. The resulting manual is in MarkDown format.

For example, the exception tree documents all the available exceptions in the code. This is very convenient to have when reaching the moment to handle an error : having an updated list of the available exceptions allows for a quick reference. Since all of them are documented in real time (or almost), this makes it easier to decide to create a new exception, and where to place it, in relation with the others.

The incoming variable list is the list of variable names received from HTML forms and queries. This is a precious documentation to get a broad view of which name is used in the code. Sometimes, the same generic name is used in too many situations, leading to confusion.

This manual is a first take on the documentation of a PHP application. A lot more information is available after a review by Exakat, and may be collected here. For example :

• List of namespaces
• List of functions, classes.
• List of classes, interfaces and traits hierarchies
• Used PHP features
• etc.

Like us, you may have a long list of auto-documentation that could end in this manual. Feel free to send us a Feature Request on the github account, so we can push it in the next version.

The Weekly audit

The weekly report is a new way to approach code reviews. It is a weekly set of five rules, extracted from the full library of Exakat rules, for which we suggest focusing your effort during the week.

Instead of having to choose among dozens of analysis, and hundreds of issues, you can simply decide to take a look at those five weekly analysis. This makes a much shorter selection of reports in the code : less clutter, more focus, and possibly, a full review of them all.

More over, the exakat.io website distribute the rules : everyone running a weekly report this week will use the same. If you need help understanding the documentation of an analysis, or want to talk about your specific situation, you can join us on slack, or even talk to colleagues and friends about it.

To extract this manual, run the following command :

php exakat.phar report -p <yourproject> -format Weekly 

You may also use an optional -filename <filename> to give it a specific folder name. Otherwise, it will simply be weekly, located as usual in the projects/<yourproject>/ folder. The resulting manual is in HTML format.

The rules change every week, and are available on Monday, along with the new Exakat version. You can enjoy the weekly selection, and the four previous selections. Note that next week’s selection is also available : this is for those of you who have nothing to fix this week. You can try to check next week’s rules : beware, as those may change without notice!

Happy PHP code reviews

All the 357 analyzers are presented in the docs, including the futuristic Detect Current Class: Detecting the current class should be done with ::class operator : you shall use ::class and static::class when detecting the current running class, instead of __CLASS__ and get_called_class(). Although correct code may be written with both versions, it may come back fast to bite you. Besides it is a common bug : 38% applications make use of them.

You can check all of the exakat reports at the gallery: exakat gallery.

Download Exakat on exakat.io, install it with Docker, upgrade it with ‘exakat.phar upgrade -u’ and like us on github.