Getting Started
===============
include::revision.txt[]


== Introduction

PHP_CompatInfo branch 1.x is still compatible with PHP4, that is from an old
age now (unmaintained).
You can find it on PEAR main site on its http://pear.php.net/package/PHP_CompatInfo[project page].

PHP_CompatInfo branch 2.x is a full rewrite with PHP5.
Since RC3 the PHP parser engine used is https://github.com/llaville/php-reflect[PHP_Reflect].
It's an improved version with "callbacks to what ever token you want" feature
from basic concept version https://github.com/sebastianbergmann/php-token-stream[PHP_TokenStream].


=== What can PHP_CompatInfo do for you ?

Depending of server API you will use, PHP_CompatInfo main goal is to give you
the minimum and maximum PHP versions, a script or a list of scripts (sources),
are required to run code.

But PHP_CompatInfo (alias phpci), may also provides on CLI (with the +phpci+ command) :

* Reference informations (MIN and MAX PHP versions) about one or more extensions :
- list all classes
- list all interfaces
- list all functions
- list all constants

* Print multiple reports group by scanned files or components
- *summary* : usage summary of each extension, interface, class, function, constant used by your sources code
- *source* : lines code count summary with or without source code
- *xml* : export result to a XML format easy to transform to xHTML or other format 
- *token* : language PHP5 special features such as try/catch/throw exception, etc 
- *extension* : usage, minimum php version and origin of each extension used by your sources code
- *namespace* : usage, minimum php version and origin of each namespace used by your sources code
- *interface* : usage, minimum php version and origin of each interface used by your sources code 
- *class* : usage, minimum php version and origin of each class used by your sources code 
- *function* : usage, minimum php version and origin of each function used by your sources code 
- *constant* : usage, minimum php version and origin of each constant used by your sources code 
- *global* : usage, minimum php version and origin of each global variable used by your sources code 


== A simple tutorial

=== Parse a single file with default options

To parse a file with the PHP5 known references of your extensions loaded, 
you have just to specify the file's location.

.API example

[source,php]
----
<?php
require_once 'Bartlett/PHP/CompatInfo.php';

$source = '/path/to/myFile.php';

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

    $allResultsAtOnce = $phpci->toArray();

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

.phpci tool example

From your PEAR _bin_dir_  directory run this command
----
$ phpci --no-configuration print --reference PHP5 --report summary /path/to/myFile.php
----
It won't use the default XML configuration file +phpcompatinfo.xml+ or +phpcompatinfo.xml.dist+
If you are sure of XML configuration settings, remove the +--no-configuration+ option.

Will print out a summary report like this one
----
    PHP COMPAT INFO REPORT SUMMARY
    -------------------------------------------------------------------------------
    FILES                         EXTENSIONS INTERFACES CLASSES FUNCTIONS CONSTANTS
    -------------------------------------------------------------------------------
    BASE: /path/to
    -------------------------------------------------------------------------------
    DIR.:
    myFile.php                            5          3      11        27         4
    -------------------------------------------------------------------------------
    A TOTAL OF
     5 EXTENSION(S) 3 INTERFACE(S) 11 CLASSE(S) 27 FUNCTION(S) 4 CONSTANT(S)
    WERE FOUND IN 1 FILE(S)
    WITH CONDITIONAL CODE LEVEL 32
    REQUIRED PHP 5.1.3 (MIN)
    -------------------------------------------------------------------------------
    Time: 2 seconds, Memory: 8.50Mb
    -------------------------------------------------------------------------------
----


=== Parse a directory with default options

If you wish to parse an entire directory, you can specify the directory location 
instead of a file.

.API example

[source,php]
----
<?php
require_once 'Bartlett/PHP/CompatInfo.php';

$source = '/path/to/myFolder';

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

    $allResultsAtOnce = $phpci->toArray();

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

.phpci tool example

From your PEAR _bin_dir_  directory and the default XML configuration file +phpcompatinfo.xml.dist+
installed into PEAR _cfg_dir_\PHP_CompatInfo. 
 
----
$ phpci print /path/to/myFolder
----
Will print out the summary report

----
    PHP COMPAT INFO REPORT SUMMARY
    -------------------------------------------------------------------------------
    FILES                         EXTENSIONS INTERFACES CLASSES FUNCTIONS CONSTANTS
    -------------------------------------------------------------------------------
    BASE: /path/to/myFolder
    -------------------------------------------------------------------------------
    DIR.:
    Cache.php                             3          0       2         4         3
    CLI.php                               3          0       8        16         6
    Configuration.php                     3          0       5        10         3
    Exception.php                         1          0       2         0         0
    Reference.php                         1          1       0         0         1
    Report.php                            2          0       2        11         3
    TokenParser.php                       2          0      14         9         3
    TokenStream.php                       4          0       3        17         3
    -------------------------------------------------------------------------------
    A TOTAL OF
     5 EXTENSION(S) 1 INTERFACE(S) 31 CLASSE(S) 47 FUNCTION(S) 6 CONSTANT(S)
    WERE FOUND IN 8 FILE(S)
    WITH CONDITIONAL CODE LEVEL 32
    REQUIRED PHP 5.1.2 (MIN)
    -------------------------------------------------------------------------------
    Time: 2 seconds, Memory: 12.00Mb
    -------------------------------------------------------------------------------
----
