= Configure CLI options
:description: Structure and contents of the XML configuration file
include::revision.txt[]
include::attributes.txt[]


== Main options

The attributes of the +<phpcompatinfo>+ element can be used to configure
PHP_CompatInfo's core functionnality.

[source,xml,numbered]
----
<?xml version="1.0" encoding="utf-8" ?>
<phpcompatinfo
    reference="ALL"
    report="summary"
    reportFileAppend="false"
    cacheDriver="file"
    recursive="false"
    fileExtensions="php, inc, phtml"
    consoleProgress="true"
    verbose="false"
    >

    <!-- ... -->
</phpcompatinfo>
----
The XML configuration above corresponds to the default behaviour of the +phpcli+ tool.

reference::
    Data dictionnary reference name. Defaults to ALL for all references 
    included in this distribution.
report::
    Kind of report to produces. May be either _summary_, _source_, _xml_, _token_,
    _extension_, _namespace_, _interface_, _class_, _function_, _constant_, _global_
reportFile::
    File that will contains the console results. Defaults output to console only.
reportFileAppend::
    If you used the _reportFile_ option, shall we replace its contents or not.
cacheDriver::
    Either you use the _file_ system cache, or don't want to cache results _null_.
recursive::
    If you want to explore sub-directories of data source provided (_true_) or not (_false_).
fileExtensions::
    A comma separated list of file extensions to parse.
consoleProgress::
    Display (_true_) or not (_false_) a progress bar while scanning data source.
verbose::
    Output more verbose information.


== Cache options

[source,xml,numbered]
----
<?xml version="1.0" encoding="utf-8" ?>
<phpcompatinfo>

    <cache id="file">
        <options>
            <gc_probability>1</gc_probability>
            <gc_maxlifetime>86400</gc_maxlifetime>
        </options>
    </cache>

</phpcompatinfo>
----
The +<cache>+ element and its +<options>+ child can be used to improve speed of parsing.

Default behavior will cache parsing results in a serialized data format on files backend of your local file system.

save_path::
    this is the path where the files (phpci_<hash>) are created.
gc_probability::
    _gc_probability_ is used to manage probability that the gc (garbage collection) routine is started. Defaults to 1
gc_maxlifetime::
    _gc_maxlifetime_ specifies the number of seconds after which data will be seen as 'garbage'
    and potentially cleaned up. Garbage collection may occur after parsing data source. Defaults to 86400 (1 day)

[caption="Tip", name="info", icon="{iconsdir}/tip.png"]
TIP: To clean the cache, set the probability (gc_probability) to 100, and reduce the life time (gc_maxlifetime) to 1 second.

Or more easily used the `clear-cache` command.
====
----
$ phpcompatinfo clear-cache
0 cache entries cleared
----
====


== References

[source,xml,numbered]
----
<?xml version="1.0" encoding="utf-8" ?>
<phpcompatinfo>

    <references>
        <reference name="Core" />
        <reference name="standard" />
    </references>

</phpcompatinfo>
----
The +<references>+ element and its +<reference>+ children can be used to specify what extension you want to detect and none others.

Default behaviour will auto-detect all your http://www.php.net/manual/en/function.extension-loaded.php[extensions loaded].


== Sets value of PHP configuration options

[source,xml,numbered]
----
<?xml version="1.0" encoding="utf-8" ?>
<phpcompatinfo>

    <php>
        <ini name="memory_limit" value="140M" />
        <ini name="short_open_tag" />
        <ini name="zend.ze1_compatibility_mode" value="false" />
    </php>

</phpcompatinfo>
----
The +<php>+ element and its +<ini>+ children can be used to configure PHP settings.

NOTE: With *phpcompatinfo* console tool, you can also sets a PHP directive value with +--ini-set+ switch.

====
----
$ phpcompatinfo --ini-set memory_limit=140M print /path/to/mySource

// both give same results
$ phpcompatinfo --ini-set short_open_tag print /path/to/mySource
$ phpcompatinfo --ini-set short_open_tag=true print /path/to/mySource
----
====


== Excluding Files or Elements from parsing

[source,xml,numbered]
----
<?xml version="1.0" encoding="utf-8" ?>
<phpcompatinfo>

    <excludes>
        <exclude id="demo">
            <directory name=".*\/Zend\/.*" />
            <file name=".*\.php5" />
            <extension name="xdebug" />
            <interface name="SplSubject" />
            <trait name="^S" />
            <class name=".*Compat.*" />
            <function name="ereg.*" />
            <function name="debug_print_backtrace" />
            <constant name="T_USE" />
        </exclude>
    </excludes>

</phpcompatinfo>
----
The +<excludes>+ element and its children can be used to configure what element to ignore from parsing.
It may be a list of directories, files, extensions, interfaces, traits, classes, functions or constants.

Default behaviour ignore nothing.

NOTE: With *phpcompatinfo* console tool, you can invoke it with the following switch: +
+--exclude-pattern <id>+

====
----
$ phpcompatinfo print --exclude-pattern demo /path/to/mySource
----
====


== Listeners

[source,xml,numbered]
----
<?xml version="1.0" encoding="utf-8" ?>
<phpcompatinfo>

    <listeners>
        <listener class="className" file="/path/to/filename">
            <arguments>
            </arguments>
        </listener>
        <listener class="PHP_CompatInfo_Listener_File" />
        <listener class="PHP_CompatInfo_Listener_Growl">
            <arguments>
                <string>PHP_CompatInfo</string>
                <array>
                    <element key="info">
                        <array>
                            <element key="display">
                                <string>Information</string>
                            </element>
                            <element key="enabled">
                                <boolean>true</boolean>
                            </element>
                        </array>
                    </element>
                    <element key="warning">
                        <array>
                            <element key="enabled">
                                <boolean>true</boolean>
                            </element>
                        </array>
                    </element>
                </array>
                <string>mamasam</string>
                <array>
                    <element key="host">
                        <string>192.168.1.2</string>
                    </element>
                    <element key="timeout">
                        <integer>10</integer>
                    </element>
                    <element key="debug">
                        <string>/path/to/logFile</string>
                    </element>
                </array>
            </arguments>
        </listener>
    </listeners>

</phpcompatinfo>
----
The +<listeners>+ element and its +<listener>+ children can be used to attach
additional observers to the parses process.

The *phpcompatinfo* console tool know in standard distribution the *File* and *Growl* listeners.

Please refer to http://growl.laurent-laville.org/[PEAR::Net_Growl] package for configuration options.

You may add your own observer. To do so, specify the class name (_class_ attribute of +<listener>+ element)
hosted by a file (_file_ attribute of the same +<listener>+ element) that implement
the http://www.php.net/manual/en/class.splobserver.php[SplObserver] interface.


== Plugins

[source,xml,numbered]
----
<?xml version="1.0" encoding="utf-8" ?>
<phpcompatinfo>

    <plugins>
        <reference name="MyReference"
            class="PEAR_CompatInfo"
            file="/path/to/PEARCompatInfo.php">
            <arguments>
            </arguments>
        </reference>
    </plugins>

</phpcompatinfo>
----
The +<plugins>+ element and its +<reference>+ children can be used to specify
your own data dictionary references.
Usefull when an extension data dictionary is not available in the standard distribution.

Default behaviour is to load all PHP4 and PHP5 known elements referenced by the
+PHP_CompatInfo_Reference_PHP5+ class.
See the _reference_ attribute of +<phpcompatinfo>+ element.

You may add your own plugin. To do so, specify the class name (_class_ attribute of +<reference>+ element)
hosted by a file (_file_ attribute of the same +<reference>+ element).
Your class should inherit from +PHP_CompatInfo_Reference_PluginsAbstract+ abstract class
that implement the +PHP_CompatInfo_Reference+ interface.

NOTE: With *phpcompatinfo* console tool, you can invoke it with the following switch: +
+--reference <name>+

====
----
$ phpcompatinfo --reference MyReference print /path/to/mySource
----
====
