The Json Configuration File

CompatInfo may used an optional config file in JSON format. It could be found either in the current, $HOME/.config/, or /etc directory.

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

E.g: BARTLETTRC=my-phpcompatinfo.json

And by setting the BARTLETT_SCAN_DIR environment variable it is possible to change directories where to search for the json config file.

E.g: BARTLETT_SCAN_DIR=.:/var/configs:/tmp/bartlett (for Linux)

E.g: BARTLETT_SCAN_DIR=.;\var\configs;\tmp\bartlett (for Windows)

Take care of different PATH_SEPARATOR and DIRECTORY_SEPARATOR in each platform.

The minimalist JSON file phpcompatinfo.json is :

{
    "source-providers": [
        {
            "in": ". as current",
            "name": "/\\.(php|inc|phtml)$/"
        }
    ],
    "plugins": [
    ],
    "analysers": [
    ],
    "services": [
    ]
}
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.
services
this entry list all services that may be used with this application.

section 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"]
    }

section Plugins

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

Take an example with the Logger plugin.

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

    {
        "name": "Logger",
        "class": "Bartlett\\Reflect\\Plugin\\LogPlugin"
    }

  • The name key is (since version 4.0.0-alpha1) comment only.

  • The class key identify the name of the class that implement the plugin features (must be fully qualified).

The LogPlugin used by default the Bartlett\Reflect\Plugin\Log\DefaultLogger class that write results to error_log

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\\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.

If you want to used the same options (Doctrine adapter with file cache) as above, you can used shortcut syntax like this.

    {
        "name": "Cache",
        "class": "Bartlett\\Reflect\\Plugin\\CachePlugin",
        "options": []
    }

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\\LogPlugin"
    }

Where options key identify an optional class logger (fully qualified. E.g YourNamespace\YourLogger).

When options key is not provided, log plugin used the default Reflect logger bundled with distribution. See Bartlett\Reflect\Plugin\Log\DefaultLogger that write results to the error log system.

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

section Analysers

There are default analysers you can use, but you are free to add your owns.

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

    {
        "name": "MyAnalyser",
        "class": "Your\\Analysers\\MyAnalyser"
    }

  • The name key is (since version 4.0.0-alpha1) comment only.

  • The class key identify the name of the class that implement your analyser (must be fully qualified).

Your analyser should implement both interfaces Bartlett\Reflect\Analyser\AnalyserInterface and PhpParser\NodeVisitor.

Then to use it in command line :

$ phpcompatinfo analyser:run /path/to/datasource my
my identify your analyser (prefix in lower case of MyAnalyser class)

Next

The Command-Line Interface

Read more

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.