Chapter 8. The Json Configuration File

[Warning]

Reflect 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 REFLECT environment variable it is possible to set the filename of phpreflect.json to something else.

E.g: REFLECT=my-phpreflect.json

The minimalist JSON file phpreflect.json is :

{
    "source-providers": [
        {
            "in": ". as current",
            "name": "/\\.(php|inc|phtml)$/"
        }
    ],
    "plugins": [
        {
            "name": "Analyser",
            "class": "Bartlett\\Reflect\\Plugin\\Analyser\\AnalyserPlugin"
        }
    ],
    "analysers" : [
        {
            "name": "Structure",
            "class": "Bartlett\\Reflect\\Analyser\\StructureAnalyser"
        }
    ]
}
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 Reflect.
analysers
this entry list all analysers that may be used with the analyser:run command.

8.1. 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"
    }

[Note]

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

8.2. section Plugins

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

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

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

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

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

[Caution]

Each name key must be unique to avoid conflicts.

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

8.2.1. Cache Plugin

[Warning]

Available only since version 2.3.0

In your phpreflect.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"
                ]
            }
        }
    }
[Tip]

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

[Note]

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

In previous configuration we used the Doctrine Cache adapter and its File system backend. See the same configuration applied with other SAPI, in Section 17.3, “File cache”

8.2.2. Log Plugin

[Warning]

Available only since version 2.4.0

In your phpreflect.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 Section 18.2, “Using your private logger” or Section 18.3, “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 Section 17.1, “Register Plugin”

8.3. section Analysers

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

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

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

    {
        "name": "Structure",
        "class": "Bartlett\\Reflect\\Analyser\\StructureAnalyser"
    }

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 structure analyser (default behavior). 

$ phpreflect analyser:run .

Named explicitly the structure analyser. 

$ phpreflect analyser:run . structure

[Caution]

Each name key must be unique to avoid conflicts.

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