Exakat 2.1.5 Review
Exakat 2.1.5 is bringing a large chest of treasures : PHP 8.0 support, with named parameters, attributes, match and added a new inventory for too many chained object. The engine upgraded the storage of Typehint and Default values, which lead to several modernisation and coverage extensions, such as ‘typehint are for interface or abstract classes’, and ‘Never used parameters’.
Code is like a series of baby steps, and a good Exakat 1.9.7 review.
PHP 8.0 support advanced
With PHP 8.0 feature freeze ready on this very day (2020, Aug 4th), a large number of new PHP features are available : they do impact the code, or the way to we use it. In particular :
All those upgrades to the PHP syntax have had an impact on the Exakat engine, which builds the representation of the code in the internal database.
Some are quite simple, like the Nullsafe operator, a.k.a. ?->, which is an option to the classic ->, or match which is an expression-like version of switch. Most of the time, they are used in the same way in an Exakat rule, and will work as usual.
Other, like the named arguments or the attributes, are changing the way Exakat navigates in the code. In particular, named argument must now find their definition thanks to a name, and not with a position. Although, the position is still important, since named arguments may be mixed with position arguments. And, of course, there is still the variadic case.
Exakat is getting ready for PHP 8.0
As of today, Exakat compatible with PHP 8.0-dev. This means that it is capable of auditing all the .phpt files provided in the source repository of PHP, in spite of any actual PHP 8.0 to parse.
It has also extended the reach of its analysis to include the new syntax, so that previous rules also make use of those new operators. So far, the unit tests are passing, so we have secured the backward compatibility. We are now in the process of reviewing and adding new code situations that arise from the usage of those new features : this means more unit tests.
It will also mean the creation of new analysis : for example, the nullsafe operator will prevent code with null values to fail, like $x?->y. Instead, the whole expression will be cancelled, and replaced by null itself. While this will save some expressions from failing, it might also push the errors further in the code, and lead to problems on the next lines. Exakat will provide new analysis for these new situations, as we detected them and add them to the reference. Send us your suggestion if you see some opportunities for new bugs to hunt.
Prepare your named arguments
Named parameters are one of the much-awaited features of PHP 8.0. It will be added to the current positional parameters, which derive their name from their position.
<?php
function power($a, $b) { return $a ** $b;}
// positional arguments : 2 ^ 3 = 8
echo power(2, 3);
// positional arguments : 3 ^ 2 = 9
echo power(3, 2);
// named arguments : 2 ^ 3 = 8
echo power(a:2, b:3);
// positional arguments : 2 ^ 3 = 8
echo power(b:3, a:2);
// mixed arguments : 2 ^ 3 = 8
echo power(2, b:3);
?>
The name of the parameter appears before the value or the expression itself, with a separating colon :. They allow for the arguments to be put at any position in the argument list, since they will be linked to their actual position at call time. This is very useful when the argument list is long, and some of the options may be skipped.
You’re in the API Now
With positional argument, the name of the argument doesn’t leak outside : you may call it $aor $bor worse, and still have a valid method. With named arguments, this is not the case anymore.
Whenever a caller is using the named parameter, it will have to use the actual names of the parameters, or PHP will emit a Fatal error :
Fatal error: Uncaught Error: Unknown named parameter $b
This means that parameter are now important, just like the class name or the method name. They are now carrying a semantic meaning that they didn’t have until PHP 8.0.
As usual, when some internals have been hidden for long, and are suddenly exposed, there are going to be some surprises. Those arguments are not always very semantic, nor well formatted.
The Parameter Names Inventory
Not only do we have some time before PHP 8.0 (december 2020), but exakat is already hard at work. In the Ambassador report, you can find the Parameter Names inventory.
This is the list of all the parameters used in the application, for methods, functions, closures and arrow functions. Here, you can see the result for an open source application :
There is the name of the parameter, and the number of times it is used as a parameter in a function or method : $name is used in 41 different methods, which makes it a very common parameter.
The local variable column indicates if the same name may also be used as a local variable name : that is, when it is not an argument. It may be a good convention to use some names as arguments, and others for local values.
<?php
// $arg is an argument
function foo($arg) {
// $var is a local variable
$var = $arg + 1;
return $var;
}
// here, $arg is only used as a local variable
function bar() {
$arg = rand(0,10);
return $arg;
}
?>
The next two columns will also show you the various typehints used with those parameters. It is interesting to see that the $handle, which may to refer to a file handle, is sometimes initialized with false and other times with null. They may not represent the same kind of data.
Parameters up for refactoring
If the most commonly used parameter names are quite unnoticeable, the bottom of the inventory shows a different world.
There, we can see that several conventions are at work, with or without upper case, with or without underscore. The names are also quite generic, but also more precise : section, anim, premium, image, buttons, plugin…
Parameter counts stats
Just above the parameter name inventory, you’ll find the parameter counts stats : in the same application, there are methods with 0 to 7 arguments, and the most common method has 1 argument. This comes with the same report.
The Weekly Audits: 2019, Week #40
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 analysis.
Weekly recommendations for PHP code review : 2020, week 2020-34
- Should Use Foreach : Use foreach instead of for when traversing an array.
- Illegal Name For Method : PHP has reserved usage of methods starting with
__for magic methods. - Switch Without Default : Always use a default statement in switch().
- Should Use Operator : Some functions duplicate the feature of an operator.
- Typehint Must Be Returned : When using a typehint for a method, it is compulsory to use a at least one return in the method’s body.
Happy PHP Code Reviews
All the 395 analyzers are presented in the docs, including the noble : Large try blocks): Avoid using too large a try block. Keep it small, and focused on the actual call that may raise the exception.
This is a new rule, thanks to @afilina for the inspiration.
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.