README

Analyzes public classes, methods, variables and functions to search for breaking changes between versions

Running

composer run example

API

Declarations

This class represents a list of public declarations accumulated from one or more files.

Public declarations include:

classes
class methods (static and instance)
public class properties
functions

Declarations can find each declaration by scanning files and directories using $declarations->scan( $dir, $exclude = array() ).

You can print, load, and save those declarations as CSV.

You can also generate a list of differences between old and new code bases, e.g. Jetpack 7.4 and Jetpack 7.5, using ->find_differences( $previous_declarations ), which returns an instance of Automattic\Jetpack\Analyzer\Differences.

$declarations = new Automattic\Jetpack\Analyzer\Declarations();

// single file
$declarations->scan( $base_path . '/class.jetpack.php' );

// OR recursively scan a directory
$exclude = array( '.git', 'vendor', 'tests', 'docker', 'bin', 'scss', 'images', 'docs', 'languages', 'node_modules' );
$declarations->scan( $base_path, $exclude );

// print the declarations
$declarations->print();

// save the declarations as CSV
$declarations->save( 'path/to/jetpack-trunk.csv' );

// load some other declarations
$jp74_declarations->load( 'path/to/jetpack-branch-7.4.csv' );

You can use instances of Declarations as input to (new Differences())->find( $new_codebase, $old_codebase )

Supported declarations:

Class
Class property (static or instance)
Class method (static or instance)
Function

Differences

A list of differences can be used to check compatibity against a set of invocations.

This is performed by parsing any external file looking for invocations. If those invocations match any functions, methods, classes or properties that have been changed between the two Jetpack versions, then a list of warnings or errors will be produced.

// load declarations from a file, or scan using ->scan()
$trunk_declarations->load( 'path/to/codebase-1.0.csv' );
$other_declarations->load( 'path/to/codebase-2.0.csv' );
// OR
$trunk_declarations->scan( 'path/to/trunk_branch', array( '.git', 'node_modules' ) );
$other_declarations->scan( 'path/to/other_branch', array( '.git', 'node_modules' ) );

$differences = new Automattic\Jetpack\Analyzer\Differences();
$differences->find( $trunk_declarations, $jp74_declarations );
$differences->print();

Supported differences:

Class missing
Class moved to another file
Class property missing
Class property moved to another file
Class method missing
Class method moved to another file
Function missing
Function moved to another file

Invocations

A list of invocations of every relevant type:

function calls
static and instance method calls
instantiation via new
references to class props

This is ALL invocations of these types. To find just the invocations of missing/different functions, look at Warnings below.

$invocations = new Automattic\Jetpack\Analyzer\Invocations();
$invocations->scan( 'path/to/example.php' ); // can be a file or directory
// OR
$invocations->scan( 'path/to/repo', array( '.git', '.gitmodules', 'assets' ) );

$invocations->print();

Supported invocations:

new Class
assign/read static Class property
invoke static Class method
call Function

Warnings

A list of warnings generated by comparing an Invocations object with a Differences object.

// assumes `$differences` and `$invocations` have already been generated as per above
$warnings = new Automattic\Jetpack\Analyzer\Warnings();
$warnings->generate( $invocations, $differences );
$warnings->print();

Supported warnings:

new Class
assign/read static Class property
invoke static Class method
call Function

automattic / jetpack-analyzer

Maintainers

Details