= Basic usage
:description: Configure the default options to match your need
include::revision.txt[]
include::attributes.txt[]


== Default options

[role="lead"]
What either you use the CLI version with the [label label-primary]#phpcompatinfo# command, or directly API functions,
PHP_CompatInfo has some default options you should learn if you want to understand results provided.

Default options printed below, may be changed either :

* by the +$options+ parameter of +PHP_CompatInfo+ class constructor, if you use the API functions
* by the XML configuration file +phpcompatinfo.xml+ or +phpcompatinfo.xml.dist+, if you use the CLI tool

.Default options
[options="header",cols="3,3,9", role="table table-bordered table-striped"]
|===========================
| Option | Default | Description
| `recursive` | false | scan recursive subdirectories or just local files
| `reference` | ALL  | data dictionary reference (all PHP4 and PHP5 informations)
| `referencePlugins` | [PHP5[...], ALL[...]] | adapters to connect to data dictionaries reference
| `verbose`        | false | output more information
| `fileExtensions` | [php, inc, phtml] | list of file extensions to scan
| `filterVersion`  | php_4.0.0  | filter results on a specific PHP or extension version
| `filterOperator` | ge   | operator to test versions for a particular relationship
(same as PHP link:http://php.net/manual/en/function.version-compare.php[version_compare])
| `cacheDriver`    | file | cache results to improve speed of next iteration
| `cacheOptions`   | []   | options specific to cache driver used
| `listeners`      | []   | none
|===========================


== Scanning files and folders

The simplest way of using PHP_CompatInfo is to provide the location of a file
or folder for PHP_CompatInfo to scan. If a folder is provided, PHP_CompatInfo
will scan all files it finds in that local folder.

[caption="Note", name="info", icon="{iconsdir}/note.png"]
NOTE: If you want sub-folders scanned, use the +recursive+ option.

.Example 1: do not use cache files, but parse directory recursively.
[source,php,numbered]
----
<?php
require_once 'Bartlett/PHP/CompatInfo/Autoload.php';

$source  = '/path/to/myFolder';
$options = array(
    'cacheDriver' => 'null',
    'recursive'   => true
);

try {
    $phpci = new PHP_CompatInfo($options);
    $phpci->parse($source);

    $allResultsAtOnce = $phpci->toArray();

} catch (PHP_CompatInfo_Exception $e) {
    die ('PHP_CompatInfo Exception : ' . $e->getMessage() . PHP_EOL);
}
----

== Specifying a Reference

PHP_CompatInfo can have multiple references installed to allow a single installation
to be used with multiple plateform. When scanning PHP code, PHP_CompatInfo can be told
which reference to use. This is done using the +reference+ option.

.Example 1: specify ALL reference to detect all extensions (not just those are loaded on your system)
[source,php,numbered]
----
<?php
require_once 'Bartlett/PHP/CompatInfo/Autoload.php';

$source  = '/path/to/myFolder';
$options = array(
    'reference' => 'ALL',
);

try {
    $phpci = new PHP_CompatInfo($options);
    $phpci->parse($source);

    $allResultsAtOnce = $phpci->toArray();

} catch (PHP_CompatInfo_Exception $e) {
    die ('PHP_CompatInfo Exception : ' . $e->getMessage() . PHP_EOL);
}
----

NOTE: If you want to use your own reference, you should have (of course) to write it,
but you must also tell where it is.

.Example 2: replaces default references provided in standard distribution
[source,php,numbered]
----
<?php
require_once 'Bartlett/PHP/CompatInfo/Autoload.php';

$source  = '/path/to/myFolder';
$options = array(
    'reference' => 'PHP5',
    'referencePlugins' => array(
        'PHP5' => array(
            'class' => 'myRefClass',
            'file'  => '/path/to/file/hosting/myRefClass.php',
            'args'  => array()
        ),

);

try {
    $phpci = new PHP_CompatInfo($options);
    $phpci->parse($source);

    $allResultsAtOnce = $phpci->toArray();

} catch (PHP_CompatInfo_Exception $e) {
    die ('PHP_CompatInfo Exception : ' . $e->getMessage() . PHP_EOL);
}
----

References are :

* `PHP5` to scan PHP4/PHP5 source code, with extensions specified or loaded on your system
* `ALL`  to scan PHP4/PHP5 source code, with extensions specified or all present in current distribution
