Exakat 1.7.0 Review

The Exakat 1.7.0 precedes Confoo 2019 by a mere day. If you are in Montreal for one of the greatest PHP and web related conference, be sure to meet us! This version is an important milestone : with the 1.7.0, we are introducing two new reports, Diplomat and History; we also added refined support for the ‘ignored’ files in the code, reducing the false positives. Luck is great, but good code starts with the Exakat 1.7.0 review!

Introducing Diplomat report

Exakat 1.7.0 starts with the new Diplomat report. This report is faster to build than the previous Ambassador report. It is focused on good PHP coding, reporting the top 10 classic issues in the code.

To be honest, there are more than 10 issues being reported, but you get the idea : those are issues that are both easy to fix and important to eradicate as they lead to nasty bugs.

Diplomat includes several other reports :

  • Top 10 issues
  • Compatibility with PHP versions
  • Code favorites, which details habits from the code
  • Extension usage
  • Bug fixes impact on your code

Until now, exakat build by default the ‘Ambassador’ report. Ambassador is the largest report to be built with Exakat, and it covers aspects of the engine : issues, documentation, inventories, compatibility, trees,…

If you want to keep generating Ambassador and Diplomat, and even other reports, such as Phpcity or History (See this one in the next section), you can configure exakat to do so. There are two different ways :

  • Modify the config/exakat.ini file, and add project_reports[] = “Ambassador”. This will apply to every code audited with this server.
  • Modify the projects//config.ini file, and add project_reports[] = “Ambassador”. This will overwrite the config/exakat.ini file, and apply only to the modified project.

You may configure several reports at the same time : simply repeat the projectreports[] = “xxx” line for each of them. And if you really want to read it all, you may also use the projectreports[] = “All” report, which will run every report available : be ready for a lot of reports.

Introducing the History Report

The history report is a special report, that spans across several audit. It collected several metrics each time a new audit is run, and store them in a SQLITE database. This keeps track of the evolution of the code across time.

Since Exakat 1.7.0, each audit is named. There are three names : dump_serial, which is an auto-increment integer, starting at 1, and build from the previous audit, when it is available. dump_time is a time stamp, taken at the time of extracting the results of the audit. This is a system timestamp, so it may be off, sometimes. Finally, there is a dump_id, which is a random integer, between 0 and PHP_INT_MAX. This helps differentiate audits if they are built on different machines.

To add the History report to your exakat configuration, configure your Exakat engine just as explained at the end of the previous section. Exakat builds as many reports as you like. You may also build them anytime after running the initial ‘project’, as long as the necessary analysis were run and dumped.

At the moment, there is no GUI for the history report. Simply query the database, to extract the information.

Half-Ignoring the Files

One of the classic sources of false positive is the usage of the ‘ignore_dirs’ directive. This directive tells exakat to ignore files and folders from the source code. This is useful when you want to audit your code, but not the framework, or the test directory, or other unrelated resources.

Yet, by ignoring the matrix within which the code is nested, it generates a large number of false positives. Imagine that you’re writing a Symfony component : omitting Symfony is a natural step, that makes the audit faster and skips reviewing Symfony’s code. But, then, any definition of \Symfony\Component\HttpFoundation\Request is now unavailable, and any usage of that class, for a typehint or an instantiation, leads to an undefined class issue : the original class is nowhere to be found.

As a workaround for this problem, exakat now review’s the ignored files as long as they are bearing a PHP extension, such as php, php3, phtml, inc, etc. When it is possible, exakat makes a quick review of the code, and collects the definitions of the classes, interfaces and traits. It uses them later to skip references to those classes.

This new feature is currently covering the CIT : classes, interfaces and traits. We’ll be adding functions and classes soon, then methods and properties later.

The speed impact is significant when you are reviewing a component for a much larger framework. As for that, it is recommended keeping the component and the framework separated when auditing.

The Weekly Audits : 2019, Week #11

Exakat includes a ‘weekly’ report : this report is built with a selection of five analyses. This means a short audit report, with few issues to review. This is not a lot to read them, and review them in your code. Everyone in the PHP community can focus on one of the classic coding problems and fix it. Talk about the weekly audit around you : you’ll find programmers facing the same challenges.

To obtain the ‘weekly’ audit, run an audit, and request the ‘Weekly’ report.

# Init the project (skip when it is already done)    
php exakat.phar init -p <yourproject> -R https://github.com/Seldaek/monolog.git -git 

# Run the project (skip when it is already done)    
php exakat.phar project -p <yourproject> 

# Export the weekly project (every monday)    
php exakat.phar report -p <yourproject> -format Weekly 

# Open projects/<yourproject>/weekly/index.html in your browser    

Every week, you can find here 5 new analysis to review in your code. In fact, when your code is clean, you can also take a quick look at the upcoming

Weekly recommendations for PHP code review : 2018, week 2019-11

  • No Class As Typehint : Avoid using classes as typehint : always use interfaces.
  • Preprocessable : The following expression is made of literal or already known values : they may be fully calculated before running PHP.
  • var_dump()… Usage : vardump(), printr() or var_export() should not be left in any production code.
  • Only Variable For Reference : When a method is requesting an argument to be a reference, it cannot be called with a literal value.
  • Inconsistent Usage : Those variables are used in various and inconsistent ways.

Happy PHP Code Reviews

All the 356 analyzers are presented in the docs, including the neat : Insufficient Typehint : An argument has a typehint, but it actually calls methods that are not listed in the interface.

It is an infrequent source of overwork in the code : 10% of applications are falling for this misguided type hint.

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.