User Guide

CompatInfo always needs a file in JSON format to run. It should be found either in the current, $HOME/.config/, or /etc directory.

By setting the COMPATINFO environment variable it is possible to set the filename of phpcompatinfo.json to something else.

E.g: COMPATINFO=my-phpcompatinfo.json

The minimalist JSON file phpcompatinfo.json is :

{
    "source-providers": [
        {
            "in": ". as current",
            "name": "/\\.(php|inc|phtml)$/"
        }
    ],
    "plugins": [
        {
            "name": "Analyser",
            "class": "Bartlett\\Reflect\\Plugin\\Analyser\\AnalyserPlugin"
        }
    ],
    "analysers" : [
        {
            "name": "Namespace",
            "class": "Bartlett\\CompatInfo\\Analyser\\NamespaceAnalyser"
        },
        {
            "name": "Extension",
            "class": "Bartlett\\CompatInfo\\Analyser\\ExtensionAnalyser"
        },
        {
            "name": "Interface",
            "class": "Bartlett\\CompatInfo\\Analyser\\InterfaceAnalyser"
        },
        {
            "name": "Trait",
            "class": "Bartlett\\CompatInfo\\Analyser\\TraitAnalyser"
        },
        {
            "name": "Class",
            "class": "Bartlett\\CompatInfo\\Analyser\\ClassAnalyser"
        },
        {
            "name": "Function",
            "class": "Bartlett\\CompatInfo\\Analyser\\FunctionAnalyser"
        },
        {
            "name": "Constant",
            "class": "Bartlett\\CompatInfo\\Analyser\\ConstantAnalyser"
        },
        {
            "name": "Summary",
            "class": "Bartlett\\CompatInfo\\Analyser\\SummaryAnalyser"
        },
        {
            "name": "Condition",
            "class": "Bartlett\\CompatInfo\\Analyser\\CodeCondAnalyser"
        },
        {
            "name": "Structure",
            "class": "Bartlett\\Reflect\\Analyser\\StructureAnalyser"
        },
        {
            "name": "Composer",
            "class": "Bartlett\\CompatInfo\\Analyser\\ComposerAnalyser"
        }
    ]
}

source-providers: this entry provide list of your data sources to parse.
plugins: this entry list all plugins added to the core base code of PHP CompatInfo.
analysers: this entry list all analysers that may be used with the analyser:run command.

Source Providers

There are lot of way to filter your data source. Each rule follow the syntax of Symfony Finder Component.

The Location is the only mandatory criteria. It tells the Finder which directory to use for the search.

In a simple directory

    {
        "in": ". as current"
    }

If you want to identify a data source easily by a short name, the alias (right of as) is compared with the --alias option constraint.

Search in several locations

    {
        "in": ". as current",
        "in": "src/"
    }

Use wildcard characters to search in the directories matching a pattern:

    {
        "in": "src/Bartlett/R*"
    }

Search directly in archives (phar, zip, tar) with the phar:// protocol

    {
        "in": "phar://path/to/archive.zip"
    }

Restrict files by name and/or extension.

    {
        "in": "phar://path/to/archive.zip",
        "name": "*.php"
    }

Restrict files by size.

    {
        "in": "phar://path/to/archive.zip",
        "name": "*.php",
        "size": "< 10K"
    }

Restrict files by last modified dates.

    {
        "in": ". as current",
        "date": "since yesterday"
    }

By default, the Finder recursively traverse directories.

Restrict the depth of traversing.

    {
        "in": ". as current",
        "depth": "< 3"
    }

Restrict location by only one directory.

    {
        "in": ". as current",
        "exclude": "vendor"
    }

Restrict location by 1 or more directories.

    {
        "in": ". as current",
        "exclude": ["vendor", "tests"]
    }

Plugins

There are a number of optional plugins you can use along with CompatInfo to add more capabilities.

The Analyser is the only mandatory plugin you should add to parse your data source.

In your phpcompatinfo.json configuration file, add in plugins section the following entry:

    {
        "name": "Analyser",
        "class": "Bartlett\\Reflect\\Plugin\\Analyser\\AnalyserPlugin"
    }

The Analyser plugin is a component from Reflect, and not from CompatInfo. Take care of namespace !

The name key identify the namespace of optional commands the plugin may provide.

Each name key must be unique to avoid conflicts.

The class key identify the name of the class that implement the plugin features.

Cache Plugin

Available only since version 3.3.0

In your phpcompatinfo.json configuration file, add in plugins section the following entry:

    {
        "name": "Cache",
        "class": "Bartlett\\Reflect\\Plugin\\Cache\\CachePlugin",
        "options": {
            "adapter": "DoctrineCacheAdapter",
            "backend": {
                "class": "Doctrine\\Common\\Cache\\FilesystemCache",
                "args": [
                    "%{TEMP}/bartlett/cache"
                ]
            }
        }
    }

You may use any environment variable that will be replaced, at run-time, by their value. E.g: TEMP, HOME

Since release 3.3.0, the HOME syntax is compatible Linux/Windows.

Take care to use the same configuration as in PHP Reflect, or you should not share the cache results.

In previous configuration we used the Doctrine Cache adapter and its File system backend. See the same configuration applied with other SAPI, in developer guide

Log Plugin

Available only since version 3.4.0

In your phpcompatinfo.json configuration file, add in plugins section the following entry:

    {
        "name": "Log",
        "class": "Bartlett\\Reflect\\Plugin\\Log\\LogPlugin",
        "options": {
            "logger": {
                "class": "YourLogger"
            },
            "conf": []
        }
    }

Where YourLogger identify your class logger (fully qualified. E.g YourNamespace\YourLogger).

See the Developer Guide for definition examples of some loggers using private logger or using monolog

And conf entry are custom plugin options to apply.

For example, to suppress logging of reflect.success event, and remove contextual data on reflect.complete event, modify your phpreflect.json configuration file as follow :

    {
        "name": "Log",
        "class": "Bartlett\\Reflect\\Plugin\\Log\\LogPlugin",
        "options": {
            "logger": {
                "class": "YourLogger"
            },
            "conf": {
                "reflect.success": false,
                "reflect.complete": {
                    "context": false
                }
            }
        }
    }

All configuration options are available, see Register Plugin of Log section.

Analysers

There are a number of optional analysers you can use along with the Reflect Analyser Plugin.

The Summary is the default analyser you should add to obtain results when you parse your data source.

In your phpcompatinfo.json configuration file, add in analysers section the following entry:

    {
        "name": "Structure",
        "class": "Bartlett\\CompatInfo\\Analyser\\SummaryAnalyser"
    }

The name key identify the name you can optionally invoke with the analyser:run command.

The two following commands do the same:

Used implicitly the summary analyser (default behavior)

$ phpcompatinfo analyser:run .

Named explicitly the summary analyser

$ phpcompatinfo analyser:run . summary

Each name key must be unique to avoid conflicts.

The class key identify the name of the class that implement the analyser features.

Conditional Code

Available only since version 3.4.0

CompatInfo is now capable to detect conditional code, mark each element in all analysers reporting, and exclude their versions from PHP min/max final results.

Let’s see with CompatInfo source code, and explain results.

The new condition analyser (CodeCondAnalyser), is able to produce such kind of report :

Data Source Analysed

Directories                                          7
Files                                              127

Conditional Code Analysis

   Condition                           REF      EXT min/Max PHP min/Max
   class_exists(\PHP_Timer)            user                 4.0.0
   defined(INTL_ICU_VERSION)           intl     2.0.0b1     5.3.7
   defined(OPENSSL_VERSION_NUMBER)     openssl  5.2.0       5.2.0
   defined(OPENSSL_VERSION_TEXT)       openssl  5.2.0       5.2.0
   function_exists(curl_version)       curl     4.0.2       4.0.2
   function_exists(event_priority_set) libevent 0.0.5       5.3.0
   Total [6]                                                5.3.7

That meens CompatInfo need at least PHP 5.3.7 if you used all conditional features. But remember, that the minimum version is only PHP 5.3.0 (see summary report).

Data Source Analysed

Directories                                          7
Files                                              127

Global Analysis

                    Count Cond PHP min Elements highlight
 Extensions         11    4    5.3.0   Core
 Namespaces         14    0    5.3.0   Bartlett\CompatInfo\Reference
 Interfaces         3     0    5.3.0   Bartlett\CompatInfo\Reference\ReferenceInterface
 Traits             0     0
 Classes            140   1    5.3.0   Bartlett\CompatInfo\Reference\Extension\RarExtension
 User Functions     5     0    5.3.0   Bartlett\CompatInfo\Reference\closure-335-372
 Internal Functions 47    2    5.2.0   json_encode
 Constants          13    3    5.3.0   __DIR__
 Total                         5.3.0

The new Cond column tell you how many condition where found in each category. And of course the condition analyser give you the details.

And finally, all other analysers show you with a C mark in front of element name when it’s excluded from PHP min/max versions, and considered as conditional code.

The Command-Line Interface

For developers who want to extend or change CompatInfo features.

Want to create a new plugin, have a look on developer’s guide in the Plugins section.
Want to create a new analyser, have a look on developer’s guide in the Analysers section.

User Guide

The Json Configuration File

Source Providers

Plugins

Cache Plugin

Log Plugin

Analysers

Conditional Code

Next