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