Build Your Own Coding Reference With Exakat

When reviewing PHP code with Exakat, there are always more issues than time to fix them. There is a time to learn from audited code, and time to focus on fixing. Both of them have their own rule set.

Exakat provides several ways to make a selection among the thousands of analyses that are available. By default, it focuses on the general set, tailored for the comprehensive Ambassador report. As you accumulate experience with your code, you’ll want to apply a custom made list.

There are several ways to for you to build your own coding reference with Exakat :

• Run a predefined set of analysis
• Create your own rule set

Run a predefined ruleset

There are several sets that are predefined in Exakat. You can find a documented list in the manual : List of recipes.

• Analyze Check for common best practices.
• Dead code Check the unused code or unreachable code.
• CompatibilityPHP74 List features that are incompatible with PHP 7.4. It is known as php-src, work in progress.
• CompatibilityPHP73 List features that are incompatible with PHP 7.3.
• CompatibilityPHP72 List features that are incompatible with PHP 7.2.
• CompatibilityPHP71 List features that are incompatible with PHP 7.1.
• Performances Check the code for slow code.
• Security Check the code for common security bad practices, especially in the Web environment.
• Coding Conventions List coding convention violations.

Each of the rule sets are a collection of several individual analysis. A rule set is used as a higher abstract layer, bringing several analyses that makes sense together. For example, Dead codecollects 25 analysis, covering Self Using Trait or Unused return value.

Rule sets are used both for analysis code and building reports. For example, the Security rule set is used both with Ambassador, for the ‘Security’ section of the report, and for the Owasp report, which only features security concerning the code.

Redefined ruleset are provided with the Exakat engine, and they are also always available.

Create a custom ruleset

To refine one of those lists further, you have to write your own rule set.

Building your own rule set allows you to choose the important rules, ignore the one that are not adapted to your coding style, or optimize the audits for speed : less analysis, more speed.

Custom ruleset are available at the engine level : this means they have to be configured in the ‘config’ folder of Exakat. Then, they are available to every code repository.

Here is how to build a list :

• spot the ‘config’ folder, next to the exakat.phar
• create a ‘themes.ini’ file inside this folder, with your favorite editor
• create a section called ‘myruleset’. You can create one rule set by sections of the ini file, so repeat from that step, and give a distinct name each time.
• Inside each section, create a analyzer variable like this :

['myruleset'] 
analyzer[] = 'Structures/AddZero';
analyzer[] = 'Structures/MultiplyByOne';
analyzer[] = 'Performances/ArrayMergeInLoops';

• There is no (reasonable) limit to this list, so add as many as you need. analyzer is important, so are the [].
• More on where to find the analysis names below.
• Save the file, then check that Exakat has spotted it, with :

php exakat.phar doctor  

• At the beginning of the doctor result, you should see something similar to this :

exakat : 
executable           : exakat
version              : 1.6.2
build                : 853
exakat.ini           : ./config/exakat.ini,
config/remotes.json,
config/themes.ini
graphdb              : gsneo4j
reports              : Ambassador
themes               :
extra themes         : myruleset
tokenslimit          : 1 000 000 000
extensions           : Drupal.phar 

• Note that themes.ini and myruleset are mentionned. This shows that Exakat found and processed the themes.ini file, and it found myruleset. Any themes that is not recognized will be omitted.

Find the Analysis Names

At that point, all you need is a good list of analysis names. Analysis names are identifiers that refers uniquely to each analysis. They are often mentioned, for documentation purposes. This is now the time to use them for the configuration.

You can find names here :

• In the manual
• In the Ambassador report
• In the weekly

In the manual

The Exakat manual includes a full section to every analysis available. Here is the entry for Abstract or Implements : the name of the analysis is in the table at the bottom, with examples, themes and examples.

In the ambassador report

In the Ambassador report, each issue is documented with a blue book as an icon. Click on any blue book icon, and it leads to the complete documentation, build in annex.

Check the list of options, right below the name of the analysis : when -P is mentioned, there is the actual name of the analysis.

In the Annex of the manual

Themes are already available with a lot of analysis, and it may be easier to weed out some of them, rather than rebuild the whole list. This is where the annex of the manual comes handy :

In the annex, each of the standard themes are listed with their list of constituting analysis. For example, Security shows the 39 analysis.

Copy this list, and paste it in the ‘themes.ini’, then, review the list of analysis, and remove or comment out any unwanted analysis.

Keep discovering new analysis

These are the ways to build a custom list of analysis, tailored for your needs. This means avoiding some rules, because they don’t apply.

But aren’t you missing out ? By keeping an eye on your favorite rules, you may also miss other interesting rules. There are literally new rules every week, and it is always a good idea to keep on the edge and check them.

This is why it is good to run a fuller Ambassador report once in a while (a month to three months, depending on your pace), and check if anything out of the ordinary is popping in your code. That may be a new analysis, or a new behavior that’s creeping into your code. And that may also be time to start checking something new.

Happy code reviews!