<commit_before>ifndef::basebackend-docbook[]

= User Guide
:description: Configuring PHP Reflect
include::revision.asciidoc[]
include::attributes.asciidoc[]
:icons!:
:iconsfont:   font-awesome
:jumbotron:
:jumbotron-fullwidth:
:footer:
:footer-fullwidth:

endif::basebackend-docbook[]

== The Json Configuration File

[WARNING]
====
[label label-primary]#Reflect# always needs a file in http://json.org/[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,json]
----
{
    "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 [label label-primary]#Reflect#.

analysers::
this entry list all analysers that may be used with the `analyser:run` command.


=== section Source Providers

[role="lead"]
There are lot of way to filter your data source. Each rule follow the syntax
of Symfony http://symfony.com/doc/current/components/finder.html[Finder] Component.

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

[source,json]
.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.

[source,json]
.Search in several locations
----
    {
        "in": ". as current",
        "in": "src/"
    }
----

[source,json]
.Use wildcard characters to search in the directories matching a pattern:
----
    {
        "in": "src/Bartlett/R*"
    }
----

[source,json]
.Search directly in archives (phar, zip, tar) with the +phar://+ protocol
----
    {
        "in": "phar://path/to/archive.zip"
    }
----

[source,json]
.Restrict files by *name* and/or extension.
----
    {
        "in": "phar://path/to/archive.zip",
        "name": "*.php"
    }
----

[source,json]
.Restrict files by *size*.
----
    {
        "in": "phar://path/to/archive.zip",
        "name": "*.php",
        "size": "< 10K"
    }
----

[source,json]
.Restrict files by last modified dates.
----
    {
        "in": ". as current",
        "date": "since yesterday"
    }
----

By default, the Finder recursively traverse directories.

[source,json]
.Restrict the depth of traversing.
----
    {
        "in": ". as current",
        "depth": "< 3"
    }
----


=== section Plugins

[role="lead"]
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:
[source,json]
----
    {
        "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.

E.g: AnalyserPlugin footnote:[{rawurl}/src/Bartlett/Reflect/Plugin/Analyser/AnalyserPlugin.php]


=== section Analysers

[role="lead"]
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:
[source,json]<commit_msg>how to configure cache in CLI mode on future version 2.3<commit_after>ifndef::basebackend-docbook[]

= User Guide
:description: Configuring PHP Reflect
include::revision.asciidoc[]
include::attributes.asciidoc[]
:icons!:
:iconsfont:   font-awesome
:jumbotron:
:jumbotron-fullwidth:
:footer:
:footer-fullwidth:

endif::basebackend-docbook[]

== The Json Configuration File

[WARNING]
====
[label label-primary]#Reflect# always needs a file in http://json.org/[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,json]
----
{
    "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 [label label-primary]#Reflect#.

analysers::
this entry list all analysers that may be used with the `analyser:run` command.


=== section Source Providers

[role="lead"]
There are lot of way to filter your data source. Each rule follow the syntax
of Symfony http://symfony.com/doc/current/components/finder.html[Finder] Component.

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

[source,json]
.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.

[source,json]
.Search in several locations
----
    {
        "in": ". as current",
        "in": "src/"
    }
----

[source,json]
.Use wildcard characters to search in the directories matching a pattern:
----
    {
        "in": "src/Bartlett/R*"
    }
----

[source,json]
.Search directly in archives (phar, zip, tar) with the +phar://+ protocol
----
    {
        "in": "phar://path/to/archive.zip"
    }
----

[source,json]
.Restrict files by *name* and/or extension.
----
    {
        "in": "phar://path/to/archive.zip",
        "name": "*.php"
    }
----

[source,json]
.Restrict files by *size*.
----
    {
        "in": "phar://path/to/archive.zip",
        "name": "*.php",
        "size": "< 10K"
    }
----

[source,json]
.Restrict files by last modified dates.
----
    {
        "in": ". as current",
        "date": "since yesterday"
    }
----

By default, the Finder recursively traverse directories.

[source,json]
.Restrict the depth of traversing.
----
    {
        "in": ". as current",
        "depth": "< 3"
    }
----


=== section Plugins

[role="lead"]
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:
[source,json]
----
    {
        "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.

E.g: AnalyserPlugin footnote:[{rawurl}/src/Bartlett/Reflect/Plugin/Analyser/AnalyserPlugin.php]

==== Cache Plugin

WARNING: Available only since version 2.3.0-beta

In your +phpreflect.json+ configuration file, add in `plugins` section the following entry:
[source,json]
----
    {
        "name": "Cache",
        "class": "Bartlett\\Reflect\\Plugin\\Cache\\CachePlugin",
        "options": {
            "adapter": "DoctrineCacheAdapter",
            "backend": {
                "class": "Doctrine\\Common\\Cache\\FilesystemCache",
                "args": [
                    "%{TEMP}/phpreflect"
                ]
            }
        }
    }
----
TIP: You may use any environment variable that will be replaced, at run-time, by their value. E.g: `TEMP`, `HOME`

In previous configuration we used the Doctrine Cache adapter and its File system backend.
See the same configuration applied with other SAPI, in
ifdef::basebackend-html[]
link:developer-guide&#45;&#45;cache-plugin.html#_file_cache[developer guide]
endif::basebackend-html[]
ifdef::basebackend-docbook[]
xref:_file_cache[]
endif::basebackend-docbook[]


=== section Analysers

[role="lead"]
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:
[source,json]
{'fraction_non_alphanumeric': 0.13841418108481052, 'fraction_numerical': 0.0015921876658528818, 'mean_word_length': 2.7854560064282845, 'pattern_counts': {'":': 55, '<': 7, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6873955', 'n_tokens_mistral': 2896, 'n_tokens_neox': 2874, 'n_words': 965}