Cobbler

What are cobblers

Cobblers mend PHP code. They apply a transformation to it.

Cobblers are a complement to code analysis : the analysis spot code to be fixed, the cobbler mends the code. Later, the analysis doesn’t find those issues anymore.

Cobbler command

To run a cobbler, use the cobble command.

php exakat cobble -p <project> <write-options> -P <Cobbler/Name>

The <project> parameter is the project on which the cobbler is run. It must have been init-ed with Exakat.

<Cobbler/Name> is the name of the cobbler to run. The list of available cobblers are in the documentation.

<write-options> configure the destination of the updated code. The available options are :

  • –branch <branch> : the modified code is written in a new branch, called <branch>. The branch may be configured for each cobbler.

  • –inplace : the analyzed code is replaced by the modified code. This cannot be reverted

  • -f <filename> : the modified code is written in the <filename> file. Only one file is written.

  • -d <dirname> : the modified codes are written in the <directory> folder. Files are written with the original name and path from the root of the repository.

  • default behavior : –branch Exakat/Cobbler/Name.

Analysis and Cobblers

The analysis come first, and then the cobbler. The analysis reads the code, assess the situation and report patterns in the code that should be fixed. Then, the results from the analysis are given to the Cobbler, as a starting point. The cobbler applies various modifications in the code, and then, produce a new code. That code is now free of issues that the analysis found.

One analysis, one cobbler

For example, Performances/PrePostIncrement is the analysis that reports post-increment that should be converted into pre-increments. This is the base analysis for the Structure/PostToPre cobbler. This cobbler updates the code and turns $a++ into ++$a, and $b-- into --$b. The resulting code is then stored into a new VCS branch, so that it may be reviewed before PR.

Cobblers are often created to apply one of the possible fixes related to one analysis. For example, Performances/PrePostIncrement might be fixed by turning the Post increment into a pre-increment, but it may also be replaced by a constant, instead of a literal.

<?php

$a++;

// Speed up the code with pre-increment
// ++$a;

// Make the ++ operation configurable
// const C = 1;
// $a = $a + C;

?>

It is not possible to apply the two cobblers at the same time, since they do not pursue the same goals. One is a performance improvement, the other one make the code configurable.

One analysis, multiple cobblers

When one analysis produces results that may be fixed with multiple cobbler, apply the following strategy : + Run the different cobblers, and write the results in different branches + Do a PR with each branch, and cherry pick the transformations

Multiple analysis, one cobbler

It is possible to apply the same cobbler to the results of multiple analysis : for example, the Structures/RemoveCode may be applied simultaneously to the analysis Structures/UselessExpressions and Classes/UnusedClasses. Both analysis spot unused code, that may well be removed.

Cobbler configuration

Cobblers take the following configuration directives :

  • Source analysis : the analysis which should be resolved by the cobbler. One or more analysis may be provided. Default values are provided, and available in the documentation.

  • Branch name : the branch used in the current VCS, to store the mended code.

  • Specific configuration : some cobblers accept customs configuration. They are detailled in the documentation of the cobbler.

INI configuration example:

[Structures/RemoveCode]
analysis[] = "Structures/UselessExpression"
analysis[] = "Classes/UnusedClass"
branch = "code-cleaning"

Cobbler tutorial

Pre-requisite

We assume that Exakat has been install-ed, and that an exakat project is already inited.

The way to run a cobbler is to call the cobble command. In this example, exakat removes the noscream @ operator, based on the Structures/NoScream analysis, and store the results in the target-branch for the project name.

> php exakat init -p phulp -R <URL> -git
> php exakat cobble -p <project name> -b <target_branch> -P Structures/RemoveNoScream