PEAR is archived and read-only

This mirror preserves historical PEAR package releases and metadata so existing references remain available.

Home » PHP » PHP_CompatInfo » Manual

Find out the minimum version and the extensions required for a piece of code to run

Summary

Features

System Requirements

Mandatory resources :

Optional resources :

About

FAQ

FAQ – Answers to most Frequently Asked Questions

PHP_CompatInfo FAQ
  1. What does it cost ?
  2. Do you offer support ?
  3. I found a bug, what shall I do ?
  4. I found an error in data dictionaries (version 1.9.0+), what shall I do ?
  5. What is PEAR ?
  6. I have a compatible PHP4/5 application with optional PHP5 code. How to ignore only PHP 5 code ?
  7. I don't want to have result (PHP array dump) display on the standard output
  8. I want to know what is the status of parsing my data source.
What does it cost ?

You can download and use it for free. But don't delete the copyright notice. You can read terms of the PHP license.

Do you offer support ?

YES if there is no answer in this Guide and if you are ready to share some informations such as : your configuration (platform Win *nix mac, PHP version, PEAR packages installed) and perharps your script.

I found a bug, what shall I do ?

You can report it with the bug tracker at PEAR.

I found an error in data dictionaries (version 1.9.0+), what shall I do ?

Report it with the bug tracker at PEAR. If error is confirmed, a new PHP_CompatInfo release will follow.

What is PEAR ?

PEAR (an acronym for PHP Extension and Application Repository) is a framework and distribution system for reusable PHP components.

Don't forget to read also the PEAR Manual and PEAR FAQ.

I have a compatible PHP4/5 application with optional PHP5 code. How to ignore only PHP 5 code ?

If you want to ignore all PHP5 code (functions, constants, extensions), you only need to add a line on your parsing (file, directory, string) options: "ignore_versions". In this example all PHP 5.0.0 to 5.2.0 code will be ignored when parsing current directory.

<?php
require_once 'PHP/CompatInfo.php';

$dir = dirname(__FILE__);
$options = array('ignore_versions' => array('5.0.0', '5.2.0'));

$pci = new PHP_CompatInfo();
$res = $pci->parseDir($dir, $options);
var_dump($res);
?>
I don't want to have result (PHP array dump) display on the standard output

Even if it's the new behavior of API 1.8.0, you can still consumes all output events with the Null renderer. Give the null value (case insensitive), as first parameter to the class constructor.

<?php
require_once 'PHP/CompatInfo.php';

$pci = new PHP_CompatInfo('null');

$res = $pci->parseData($datasource);

// display results is only produced by the line below
var_dump($res);
?>
I want to know what is the status of parsing my data source.

For a single file, it's not necessary to have a progress bar or a message wait. But when you parse a directory with many subdirectories and files, it may take some time.

Depending of interface you're running (CLI or Web) you've two ways to display a progress bar or a message wait.

If you specify a progress bar to wait and you don't have PEAR::Console_ProgressBar package installed, default use standard text messages (no error stop the process).

Wait while parsing data source ...
Wait while parsing file "C:\wamp\tmp\Services_W3C_CSSValidator-0.1.0\CSSValidator.php"

On CLI with pci command, give the -p|--progress switch with either bar (for a progress bar), or text (for a simple text message).

pci --summarize --progress bar --dir C:\Temp\beehiveforum082\forum

On CLI without pci command, use the second parameter (driver specific options) of class constructor. Give progress key with bar (for a progress bar), or text (for a simple text message). And don't forget to de-activate silent mode (default is on for behavior backward compatibility).

<?php
require_once 'PHP/CompatInfo.php';

$driverType    = 'csv';
$driverOptions = array('silent' => false, 'progress' => 'bar');

$pci = new PHP_CompatInfo($driverType, $driverOptions);
?>

It will produce something like:

-  79/419 files [====>-----------------]  18.85% Elapsed Time: 00:28.93

For Web SAPI see the full example available in distribution into examples directory named pci180_parsefolder_tohtml.php. It used the PEAR::HTML_Progress2 package to produce a progress bar with COMET method (not AJAX).

News

News – What is New in version ?

Choose the right version

If you need PHP3 detection, DO NOT use version 1.5.0 or greater, but the latest release of 1.4 branch (1.4.3)

Version 0.7.x
Version 0.8.x
Version 1.0.x
Version 1.1.x
Version 1.2.x
Version 1.3.x
Version 1.4.x
Version 1.5.x
Version 1.6.x
Version 1.7.x
Version 1.8.x

Rewrites of core API following the MVC pattern came from a user request that wanted to customized its CLI output. Even if output-level switch already exists, there is no easy way with no process-logic dependency.

A word about the new architecture: Parser logic may be found in class PHP_CompatInfo_Parser, while PHP_CompatInfo class is still the main controller, but just a wrapper to parser methods. Each output format (csv, xml, text, html, array, null) is produced by an independant renderer ( PHP_CompatInfo_Renderer_Csv, PHP_CompatInfo_Renderer_Xml, PHP_CompatInfo_Renderer_Text, PHP_CompatInfo_Renderer_Html, PHP_CompatInfo_Renderer_Array, PHP_CompatInfo_Renderer_Null ) with the common interface PHP_CompatInfo_Renderer

To create your own renderer or just customize a bit an exists renderer, please have a look on example named pci180_parsedir_tohtml.php

Here are the list of news and changes since previous API:

Version 1.9.x

With API 1.8.0, there is a limit in class (internal, and end-user defined) detection. This limit is also valuable for lot of constants and PHP extensions.

API 1.8.0 detected PHP4 classes constructors as simple functions, that produce wrong results, especially if class name is also an extension function. Example: HTTP_Request class from PEAR package may be also found into pecl_http extension.

API 1.9.0 introduce a 3 categories dictionary system: class, constant and function.

Each dictionary can include data from 0 to N extensions depending of your need of detection (and/or platform running).

Extensions Support List (aka ESL) default built include following 30 extensions:

PHP4 users may extend this list by hand and construct their own with other available extensions provided into package distribution.

PHP5 users may also extend this list by hand, but there is a script named pciconf (pciconf.bat for Windows users) that can simplify the build process.

API 1.9.0 provided also new methods to retrieve easily information from array results, global or for a specific file in results list. These methods are:

Installing PHP_CompatInfo

Installing PHP_CompatInfo – two solutions: auto and manual

Installation Process

PHP_CompatInfo (alias PCI) should be installed using the PEAR Installer. This installer which provides a distribution system for PHP packages and full application, support channels architecture and custom file tasks. Learn more about new features in PEAR 1.4

Although using the PEAR Installer is the most easy way to install PCI, you can install PCI manually. For manual installation, do the following (steps 11-12 are for version 1.9.0+):

  1. Download the most recent release archive from http://pear.php.net/get/PHP_CompatInfo/ and extract it to a directory that is listed in the include_path of your php.ini configuration file.
  2. Prepare the pci.bat script:
    For windows users only
    1. Rename the compatinfo.bat script to pci.bat.
    2. Replace the @php_bin@ string in it with the path to your PHP command-line interpreter. Replace also the @bin_dir@ string in it with the directory where you will put the pci script.
    3. Copy it to a directory that is in your PATH
  3. Prepare the pci script:
    1. Rename the pci.php file to pci.
    2. Replace the @php_bin@ string in it with the path to your PHP command-line interpreter (usually /usr/bin/php).
    3. Copy it to a directory that is in your PATH and make it executable (chmod +x pci), or for windows users copy it to the directory corresponding to @bin_dir@ string (see previous modification).
  4. Prepare the html renderer script (CompatInfo/Renderer/Html.php):
    1. Replace the @data_dir@ string in it with the path where you have extracted the downloaded package.
    2. If you do not move the stylesheet pci.css to another location, remove the line with . '@package_name@' . DIRECTORY_SEPARATOR.
  5. Download also, release archive of PEAR::Console_Table package version 1.0.5 (or better), from http://pear.php.net/package/Console_Table/download and extract it to a directory that is listed in the include_path of your php.ini configuration file.
  6. Download also, release archive of PEAR::Console_GetArgs package version 1.3.3 (or better), from http://pear.php.net/package/Console_GetArgs/download and extract it to a directory that is listed in the include_path of your php.ini configuration file.
  7. Download also, release archive of PEAR::File_Find package version 1.3.0 (or better), from http://pear.php.net/package/File_Find/download and extract it to a directory that is listed in the include_path of your php.ini configuration file.
  8. Download also, release archive of PEAR::Event_Dispatcher package version 1.0.0 (or better), from http://pear.php.net/package/Event_Dispatcher/download and extract it to a directory that is listed in the include_path of your php.ini configuration file.
  9. Depending of what renderer (XML) you will use, you may also need to download release archive of PEAR::XML_Util package version 1.1.4 (or better), from http://pear.php.net/package/XML_Util/download and extract it to a directory that is listed in the include_path of your php.ini configuration file.
  10. Depending of what renderer (HTML) you will use, you may also need to download release archive of PEAR::HTML_Table package version 1.8.2 (or better), from http://pear.php.net/package/HTML_Table/download and extract it to a directory that is listed in the include_path of your php.ini configuration file.
  11. Prepare the pciconf.bat script:
    For windows users only
    1. Replace the @php_bin@ string in it with the path to your PHP command-line interpreter. Replace also the @bin_dir@ string in it with the directory where you will put the pciconf script.
    2. Copy it to a directory that is in your PATH
  12. Prepare the pciconf script:
    1. Rename the configure.php file to pciconf.
    2. Replace the @php_bin@ string in it with the path to your PHP command-line interpreter (usually /usr/bin/php).
    3. Copy it to a directory that is in your PATH and make it executable (chmod +x pci), or for windows users copy it to the directory corresponding to @bin_dir@ string (see previous modification).
    4. Replace the @php_dir@ string in it with the path to your PEAR directory installation.

Getting started

Overview

Overview – features and usage patterns

In brief

There are two types of interface to run a PHP_CompatInfo (alias PCI) script detection: CLI and web. All PCI features (since 1.7.0) are available on both interface.

It's up to you to choose what is the best usage for you.

Accuracy of detection

PCI may detect without error and with a great precision, any simple PHP scripts that have no switch conditions such as these ones : function_exists or version_compare.

<?php
// ...
if (function_exists('debug_backtrace')) {
    $backtrace = debug_backtrace();
} else {
    $backtrace = false;
}

if (version_compare(phpversion(), '5.0.0', '<')) {
    include_once 'PHP/Compat.php';
    PHP_Compat::loadFunction('ob_get_clean');
    PHP_Compat::loadConstant('PHP_EOL');
}
// ...
?>

Don't be afraid, PCI can still be use, even if your PHP scripts have these conditions or any others, but you should help it, to adjust the parser accuracy with one or more options. See the parser options reference list for details and advanced detection section.

Basic detection

Basic detection – parse data source with default options

Detection of a single file

In most case, the basic detection is enough. But sometimes, we will need to adjust accuracy of parser to give the best result. It is possible with $option, the second parameter of each parser method. See parser options list for details.

Suppose we have to detect which PHP version we need to run this script named "math.php"

<?php
$nb = bcsub(1.234, 5, 4);
if (preg_match('/^-/', $nb)) {
    echo 'minus';
}
?>

We will use this very simple detection script.

<?php
require_once 'PHP/CompatInfo.php';

$source = dirname(__FILE__) . DIRECTORY_SEPARATOR . 'math.php';

$info = new PHP_CompatInfo();
$info->parseFile($source);
// you may also use unified method:  $info->parseData($source);
?>

Default output used the Array renderer (we will talk about it and other renderers later; don't be afraid if you don't know what is it yet). Here are the raw results we got on standard output :

array (
  'ignored_files' =>
  array (
  ),
  'ignored_functions' =>
  array (
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '4.0.0',
  'classes' =>
  array (
  ),
  'extensions' =>
  array (
    0 => 'bcmath',
    1 => 'pcre',
  ),
  'constants' =>
  array (
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 0,
  ),
)

It means that we need at least PHP 4.0.0 to run the "math.php" script. with two PHP extensions

loaded.

Detection of a directory

Rather than parsing file after file of an application, you my give the root of your application path as the main directory to parse. Default is recursive parsing: that mean each directory children will be also parsed. And only files with extension

will be proceed.

Suppose we have to detect which PHP version we need to run the PEAR::File_Find package release 1.3.0

First begin to download the archive from http://pear.php.net/package/File_Find/download/1.3.0 and extract the full contents to a temporary directory (in our example its '/tmp')

We will use this very simple detection script.

<?php
require_once 'PHP/CompatInfo.php';

$source = '/tmp/File_Find-1.3.0';

$info = new PHP_CompatInfo();
$info->parseDir($source);
// you may also use unified method:  $info->parseData($source);
?>

Results displayed:

array (
  'ignored_files' =>
  array (
    0 => '/tmp/File_Find-1.3.0/package.xml',
    1 => '/tmp/File_Find-1.3.0/tests/01glob.phpt',
    2 => '/tmp/File_Find-1.3.0/tests/02maptree.phpt',
    3 => '/tmp/File_Find-1.3.0/tests/03maptreemultiple.phpt',
    4 => '/tmp/File_Find-1.3.0/tests/04search.phpt',
    5 => '/tmp/File_Find-1.3.0/tests/05search_inside.phpt',
    6 => '/tmp/File_Find-1.3.0/tests/06match_shell.phpt',
    7 => '/tmp/File_Find-1.3.0/tests/bug2773.phpt',
  ),
  'ignored_functions' =>
  array (
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '4.3.0',
  'classes' =>
  array (
    0 => 'File_Find',
  ),
  'extensions' =>
  array (
    0 => 'pcre',
  ),
  'constants' =>
  array (
    0 => 'FALSE',
    1 => 'NULL',
    2 => 'PHP_OS',
    3 => 'PREG_SPLIT_DELIM_CAPTURE',
    4 => 'PREG_SPLIT_NO_EMPTY',
    5 => 'TRUE',
    6 => '__FILE__',
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 4,
  ),
  '/tmp/File_Find-1.3.0/Find.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.3.0',
    'classes' =>
    array (
      0 => 'File_Find',
    ),
    'extensions' =>
    array (
      0 => 'pcre',
    ),
    'constants' =>
    array (
      0 => 'FALSE',
      1 => 'NULL',
      2 => 'PREG_SPLIT_DELIM_CAPTURE',
      3 => 'PREG_SPLIT_NO_EMPTY',
      4 => 'TRUE',
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 4,
    ),
  ),
  '/tmp/File_Find-1.3.0/tests/setup.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.0.0',
    'classes' =>
    array (
    ),
    'extensions' =>
    array (
    ),
    'constants' =>
    array (
      0 => 'PHP_OS',
      1 => '__FILE__',
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 0,
    ),
  ),
)

means that package PEAR::File_Find 1.3.0 need at least PHP 4.3.0 with extension pcre.

cond_cond offset 0 is set to 4. That means there are conditional code (constant condition) implemented in source code (with php defined function).

If you have a look on source code, you will see that all conditions referred to private package constant FILE_FIND_DEBUG

You may avoid to read the source code to know the constant name, if you specify the debug option when parsing the directory.

<?php
require_once 'PHP/CompatInfo.php';

$source = '/tmp/File_Find-1.3.0';

$info = new PHP_CompatInfo();
$info->parseDir($source, array('debug' => true));
?>

And you will see in displayed results, something like :

  'cond_code' =>
  array (
    0 => 4,
    1 =>
    array (
      0 =>
      array (
      ),
      1 =>
      array (
      ),
      2 =>
      array (
        0 => 'FILE_FIND_DEBUG',
      ),
    ),

cond_code offset 1 is an array available only when debug mode is set to true. In this array :

Advanced detection

Advanced detection – parse data source with additional options

Detection of a single file

If your file implement code condition that is optional and don't break main goal, such as, for example : if function_exists then I do something, else I do something else.

Solution is very easy: You have to specify what function required should be considered as optional.

Suppose we have to detect which PHP version we need to run this chunk of script named "errorHandler.php". With standard behavior, PCI returns PHP 4.3.0 (because debug_backtrace came with version 4.3.0). So, if we ignore function debug_backtrace to find out the minimum version, we will get the real and true result.

<?php
// ...
if (function_exists('debug_backtrace')) {
    $backtrace = debug_backtrace();
} else {
    $backtrace = false;
}
// ...
?>

We will use another very simple detection script. Have a look on options array given as second parameter (here is the magic).

<?php
require_once 'PHP/CompatInfo.php';

$source  = dirname(__FILE__) . DIRECTORY_SEPARATOR . 'errorHandler.php';
$options = array('ignore_functions' => array('debug_backtrace'));

$info = new PHP_CompatInfo();
$info->parseFile($source, $options);
// you may also use unified method:  $info->parseData($source, $options);
?>

And displayed results are :

array (
  'ignored_files' =>
  array (
  ),
  'ignored_functions' =>
  array (
    0 => 'debug_backtrace',
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '4.0.0',
  'classes' =>
  array (
  ),
  'extensions' =>
  array (
  ),
  'constants' =>
  array (
    0 => 'FALSE',
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 1,
  ),
)

that means chunk of script named "errorHandler.php" need PHP 4.0.0, have condition code (function condition : cond_code = 1), and php debug_backtrace function was excluded from scope.

Since version 1.7.0, you may catch this situation (more easily), and exclude from scope all functions that are conditionned by a function_exists. See example that follow.

Other alternative is to use ignore_functions_match option.

<?php
require_once 'PHP/CompatInfo.php';

$source  = dirname(__FILE__) . DIRECTORY_SEPARATOR . 'errorHandler.php';
$options = array('ignore_functions_match' => array('function_exists', array('/.*/')));

$info = new PHP_CompatInfo();
$info->parseFile($source, $options);
// you may also use unified method:  $info->parseData($source, $options);;
?>

The string function_exists as first parameter, tell to ignore function(s) that match only conditionnal code with php function_exists().

The other possibility is string preg_match, that give more freedom, and catch function that match the pattern (without condition).

While array as second parameter, gave a list of pattern (function name) that must be catch and ignored.

Detection of a directory

Parsing a full directory, recursively or not, is no more difficult than detect PHP version of a single file.

This new example is based on auto detection of HTML_CSS 1.5.1 distribution. As we will see, basic detection is not accurate as it should be. But with an option we can get the real result (PHP minimum = 4.3.0).

First begin to download the archive from http://pear.php.net/package/HTML_CSS/download/1.5.1 and extract the full contents to a temporary directory (in our example its '/tmp')

We will focus on two important files: CSS.php and CSS/Error.php. So we will indicate to PCI to ignore examples/, and tests/ directories.

Here is the detection script:

<?php
require_once 'PHP/CompatInfo.php';

$source  = '/tmp/HTML_CSS-1.5.1';
$options = array('ignore_dirs' => array('examples', 'tests'));

$info = new PHP_CompatInfo();
$info->parseDir($source, $options);
// you may also use unified method:  $info->parseData($source, $options);
?>

And displayed results are :

array (
  'ignored_files' =>
  array (
    0 => '/tmp/HTML_CSS-1.5.1/ChangeLog',
    1 => '/tmp/HTML_CSS-1.5.1/package.xml',
    2 => '/tmp/HTML_CSS-1.5.1/tests/AllTests.php',
    3 => '/tmp/HTML_CSS-1.5.1/tests/HTML_CSS_TestSuite_Bugs.php',
    4 => '/tmp/HTML_CSS-1.5.1/tests/HTML_CSS_TestSuite_Standard.php',
    5 => '/tmp/HTML_CSS-1.5.1/tests/stylesheet.css',
    6 => '/tmp/HTML_CSS-1.5.1/examples/CSS_Advanced.php',
    7 => '/tmp/HTML_CSS-1.5.1/examples/CSS_DisplayOnline.php',
    8 => '/tmp/HTML_CSS-1.5.1/examples/css_errorstack_custom.php',
    9 => '/tmp/HTML_CSS-1.5.1/examples/css_errorstack_logger.php',
    10 => '/tmp/HTML_CSS-1.5.1/examples/css_error_custom.php',
    11 => '/tmp/HTML_CSS-1.5.1/examples/css_error_ignore.php',
    12 => '/tmp/HTML_CSS-1.5.1/examples/css_error_logger.php',
    13 => '/tmp/HTML_CSS-1.5.1/examples/CSS_grepStyles.php',
    14 => '/tmp/HTML_CSS-1.5.1/examples/CSS_InHeader.php',
    15 => '/tmp/HTML_CSS-1.5.1/examples/CSS_Inline.php',
    16 => '/tmp/HTML_CSS-1.5.1/examples/CSS_Logger.php',
    17 => '/tmp/HTML_CSS-1.5.1/examples/CSS_parseData.php',
    18 => '/tmp/HTML_CSS-1.5.1/examples/CSS_req12194_atrule_api.php',
    19 => '/tmp/HTML_CSS-1.5.1/examples/CSS_req12194_atrule_parser.php',
    20 => '/tmp/HTML_CSS-1.5.1/examples/CSS_Stylesheet.php',
    21 => '/tmp/HTML_CSS-1.5.1/examples/CSS_validate.php',
  ),
  'ignored_functions' =>
  array (
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '5.0.0',
  'classes' =>
  array (
    0 => 'Services_W3C_CSSValidator',
  ),
  'extensions' =>
  array (
    0 => 'date',
    1 => 'pcre',
  ),
  'constants' =>
  array (
    0 => 'E_USER_ERROR',
    1 => 'E_USER_NOTICE',
    2 => 'E_USER_WARNING',
    3 => 'FALSE',
    4 => 'NULL',
    5 => 'PHP_OS',
    6 => 'PREG_SET_ORDER',
    7 => 'PREG_SPLIT_DELIM_CAPTURE',
    8 => 'TRUE',
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 1,
  ),
  '/tmp/HTML_CSS-1.5.1/CSS.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '5.0.0',
    'classes' =>
    array (
      0 => 'Services_W3C_CSSValidator',
    ),
    'extensions' =>
    array (
      0 => 'date',
      1 => 'pcre',
    ),
    'constants' =>
    array (
      0 => 'FALSE',
      1 => 'NULL',
      2 => 'PHP_OS',
      3 => 'PREG_SET_ORDER',
      4 => 'PREG_SPLIT_DELIM_CAPTURE',
      5 => 'TRUE',
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 1,
    ),
  ),
  '/tmp/HTML_CSS-1.5.1/CSS/Error.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.3.0',
    'classes' =>
    array (
    ),
    'extensions' =>
    array (
      0 => 'date',
    ),
    'constants' =>
    array (
      0 => 'E_USER_ERROR',
      1 => 'E_USER_NOTICE',
      2 => 'E_USER_WARNING',
      3 => 'FALSE',
      4 => 'NULL',
      5 => 'TRUE',
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 0,
    ),
  ),
)

As we can read, PHP 5.0.0 is required to run the package.

Yes, but its the wrong result. HTML_CSS 1.5.1 require only PHP 4.3.0 to run.

If you have cond_code offset with a value different than zero, you are almost sure that the version given is wrong.

So why we get such result ?

Package PEAR::HTML_CSS 1.5.1 as many application/extension use conditional code to emulate function that are unavailable for previous PHP versions. Its means that HTML_CSS use the php function function_exists() to implement such alternative.

To illustrate our purpose, we can find in source code (CSS.php) :

<?php
// ...
    if (function_exists('file_put_contents')) {
        file_put_contents($filename, $this->toString());
    } else {
        $file = fopen($filename, 'wb');
        fwrite($file, $this->toString());
        fclose($file);
    }
// ...
?>

PHP function file_put_contents() came with version 5.0.0; That is the reason of wrong parsing result. But we can catch such conditional code.

Let's see now how to set the good accuracy with conditional code analysis.

Conditional Code Analysis

Conditional Code Analysis – improve accuracy detection with conditional code

Categories

As briefly introduced at end of advanced detection chapter, we will learn now that there are 3 categories of conditional code that could give wrong result, if there are not catched properly.

These categories are :

How to catch them with web interface

At the beginning of first version that catch conditional code, there were only 3 options: ignore_functions, ignore_extensions and ignore_constants.

Incovenient with these options, is that you should know the source code to parse, and identify whose functions, extensions or constants to avoid.

Version 1.7.0 of API has introduced the ability to add name patterns to identify all or part of functions, extensions, constants to ignore from parsing. You should use now these options: ignore_functions_match, ignore_extensions_match or ignore_constants_match.

Let's take a look with an example, how it's easy to catch whatever you want to exclude from parsing. We will take again example of PEAR::HTML_CSS 1.5.1 package already seen in advanced directory detection .

<?php
require_once 'PHP/CompatInfo.php';

$datasource = '/tmp/HTML_CSS-1.5.1';
$options    = array(
    'ignore_dirs' => array('examples', 'tests'),
    'ignore_functions_match' => array('function_exists', array('/.*/')),
    'ignore_extensions_match' => array('extension_loaded', array('/.*/')),
    'ignore_constants_match' => array('defined', array('/.*/')),
    );

$pci = new PHP_CompatInfo();
$pci->parseData($datasource, $options);
?>

Here we catch all standard conditional code (function_exists, extension_loaded, defined) what match all names (regular expression given by array('/.*/')).

To catch what ever function you want, use preg_match rather than function_exists.

It's also true for extension_loaded and defined

With preg_match you are really free to ignore a single function, a group set or all functions, only by giving the good name pattern.

Example to ignore all functions prefixed by xdebug_ :

<?php
require_once 'PHP/CompatInfo.php';

$datasource = '/tmp/HTML_CSS-1.5.1';
$options    = array(
    'ignore_functions_match' => array('preg_match', array('/^xdebug_/')),
    );

$pci = new PHP_CompatInfo();
$pci->parseData($datasource, $options);
?>

How to catch them with CLI

If you use the command-line parser with pci script, the solution is a bit different.

To catch cond_code = 1 (function), you must run the command pci -inm functions-match.txt where functions-match.txt is a text file, that identify on each line a new condition.

Each blank line or beginning with ; will be skipped (proceed as comment line like in php.ini)

If first non blank character is an equal sign (=), then you can catch what ever function you want with a preg_match condition (see xdebug example in previous section (web interface)

Example of text file contents

;=^xdebug_
;=alias$
.*
;file_put_contents

Do not confuse a regular expression beginning with equal sign (=), and the same line without =.

In first case you will catch all functions that match the name pattern given found in all source code, while second case try to catch only matches found with if function_exists('') condition.

It's also true for extensions and constants, we will see them now.

To catch cond_code = 2 (extension), you must run the command pci -iem extensions-match.txt where extensions-match.txt is a text file, that identify on each line a new condition.

Each blank line or beginning with ; will be skipped (proceed as comment line like in php.ini)

If first non blank character is an equal sign (=), then you can catch what ever extension you want with a preg_match condition.

Example of text file contents

;=xdebug
;sqlite
=gd
;=sapi_apache

To catch cond_code = 4 (constant), you must run the command pci -icm constants-match.txt where constants-match.txt is a text file, that identify on each line a new condition.

Each blank line or beginning with ; will be skipped (proceed as comment line like in php.ini)

If first non blank character is an equal sign (=), then you can catch what ever constant you want with a preg_match condition.

Example of text file contents

=PHP_EOL
=DATE_RSS
;FILE_FIND_VERSION

The Command-Line Parser

The Command-Line Parser – parsing data source with CLI

Switches and options

The Command-Line Parser can be invoked through the pci command.

Let's take a look at the command-line parser switches:

Usage: pci [options]

  -d   --dir (optional)value                      Parse DIR to get its
                                                  compatibility info ()
  -f   --file (optional)value                     Parse FILE to get its
                                                  compatibility info ()
  -s   --string (optional)value                   Parse STRING to get its
                                                  compatibility info ()
  -v   --verbose (optional)value                  Set the verbose level (1)
  -n   --no-recurse                               Do not recursively parse files

                                                  when using --dir
  -if  --ignore-files (optional)value             Data file name which contains
                                                  a list of file to ignore
                                                  (files.txt)
  -id  --ignore-dirs (optional)value              Data file name which contains
                                                  a list of directory to ignore
                                                  (dirs.txt)
  -in  --ignore-functions (optional)value         Data file name which contains
                                                  a list of php function to
                                                  ignore (functions.txt)
  -ic  --ignore-constants (optional)value         Data file name which contains
                                                  a list of php constant to
                                                  ignore (constants.txt)
  -ie  --ignore-extensions (optional)value        Data file name which contains
                                                  a list of php extension to
                                                  ignore (extensions.txt)
  -iv  --ignore-versions values(optional)         PHP versions - functions to
                                                  exclude when parsing source
                                                  code (5.0.0)
  -inm --ignore-functions-match (optional)value   Data file name which contains
                                                  a list of php function pattern

                                                  to ignore
                                                  (functions-match.txt)
  -iem --ignore-extensions-match (optional)value  Data file name which contains
                                                  a list of php extension
                                                  pattern to ignore
                                                  (extensions-match.txt)
  -icm --ignore-constants-match (optional)value   Data file name which contains
                                                  a list of php constant pattern

                                                  to ignore
                                                  (constants-match.txt)
  -fe  --file-ext (optional)value                 A comma separated list of file

                                                  extensions to parse (only
                                                  valid if parsing a directory)
                                                  (php, php4, inc, phtml)
  -r   --report (optional)value                   Print either "xml" or "csv"
                                                  report (text)
  -o   --output-level (optional)value             Print Path/File + Version with

                                                  additional data (31)
  -t   --tab (optional)value                      Columns width (29,12,20)
  -p   --progress (optional)value                 Show a wait message [text] or
                                                  a progress bar [bar] (bar)
  -S   --summarize                                Print only summary when
                                                  parsing directory
  -V   --version                                  Print version information
  -h   --help                                     Show this help
-d | --dir

pci -d directory

Runs the parser with all default options, and try to analyze content of files into directory identified by switch -d or --dir

-f | --file

pci -f file

Runs the parser with all default options, and try to analyze content of a single file identified by switch -f or --file

-s | --string

pci -s string

Runs the parser with all default options, and try to analyze content of a chunk of code (string) designed by switch -s or --string

-v | --verbose

pci -v number -d directory

Runs the parser with all default options, and try to analyze content of files into directory identified by switch -d or --dir with the level of detail given by number and switch -v or --verbose

Verbose level goes from 0 (no extra information) to 7 (full extra details).

  • Level 0 give only parsing results of data source (directory, file, string). For example: pci -v 0 -d /tmp/Services_W3C_CSSValidator-0.1.0 give 
    +-----------------------------+---------+---+------------+--------------------+
| Files                       | Version | C | Extensions | Constants/Tokens   |
+-----------------------------+---------+---+------------+--------------------+
| ...W3C_CSSValidator-0.1.0/* | 5.1.0   | 4 | dom        | ...CTORY_SEPARATOR |
|                             |         |   |            | E_ALL              |
|                             |         |   |            | FALSE              |
|                             |         |   |            | NULL               |
|                             |         |   |            | TRUE               |
|                             |         |   |            | __FILE__           |
|                             |         |   |            | instanceof         |
|                             |         |   |            | protected          |
|                             |         |   |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...r-0.1.0/CSSValidator.php | 5.1.0   | 0 | dom        | FALSE              |
|                             |         |   |            | NULL               |
|                             |         |   |            | TRUE               |
|                             |         |   |            | protected          |
|                             |         |   |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...0.1.0/tests/AllTests.php | 5.0.0   | 4 |            | __FILE__           |
|                             |         |   |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...W3C_CSSValidatorTest.php | 5.0.0   | 4 |            | ...CTORY_SEPARATOR |
|                             |         |   |            | __FILE__           |
|                             |         |   |            | protected          |
|                             |         |   |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...les/validate_atrules.php | 4.0.0   | 0 |            | E_ALL              |
|                             |         |   |            | TRUE               |
+-----------------------------+---------+---+------------+--------------------+
| ...ples/validate_byfile.php | 4.0.0   | 0 |            | E_ALL              |
|                             |         |   |            | TRUE               |
+-----------------------------+---------+---+------------+--------------------+
| ...mples/validate_byuri.php | 4.0.0   | 0 |            | E_ALL              |
|                             |         |   |            | TRUE               |
+-----------------------------+---------+---+------------+--------------------+
| ...es/validate_fragment.php | 4.0.0   | 0 |            | E_ALL              |
|                             |         |   |            | TRUE               |
+-----------------------------+---------+---+------------+--------------------+
| ...0/CSSValidator/Error.php | 5.0.0   | 0 |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...CSSValidator/Message.php | 5.0.0   | 0 |            | NULL               |
|                             |         |   |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...SSValidator/Response.php | 5.0.0   | 0 |            | instanceof         |
|                             |         |   |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...CSSValidator/Warning.php | 4.0.0   | 0 |            |                    |
+-----------------------------+---------+---+------------+--------------------+
  • Level 1 give same details as level 0, plus command line resume. For example: pci -v 1 -d /tmp/Services_W3C_CSSValidator-0.1.0 give 
    Command Line resume :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+
| summarize               | FALSE                                             |
| output-level            | 31                                                |
| verbose                 | 1                                                 |
| dir                     | /tmp/Services_W3C_CSSValidator-0.1.0              |
+-------------------------+---------------------------------------------------+
  • Level 2 give same details as level 0, plus parser options used. For example: pci -v 2 -d /tmp/Services_W3C_CSSValidator-0.1.0 give 
    Parser options :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+
| file_ext                | php                                               |
|                         | php4                                              |
|                         | inc                                               |
|                         | phtml                                             |
| recurse_dir             | TRUE                                              |
| debug                   | FALSE                                             |
| is_string               | FALSE                                             |
| ignore_files            |                                                   |
| ignore_dirs             |                                                   |
+-------------------------+---------------------------------------------------+
  • Level 3 is equivalent to level 2 + level 1 + level 0.
  • Level 4 give same details as level 0, plus list of php functions used with their version and source (extension PECL or standard). For example: pci -v 4 -d /tmp/Services_W3C_CSSValidator-0.1.0 give 
    Debug:

+---------+-----------------+-----------+------+
| Version | Function        | Extension | PECL |
+---------+-----------------+-----------+------+
| 4.0.0   | in_array        |           | no   |
| 4.0.0   | file_exists     |           | no   |
| 4.0.0   | is_bool         |           | no   |
| 4.0.0   | intval          |           | no   |
| 4.0.0   | defined         |           | no   |
| 4.0.0   | define          |           | no   |
| 4.0.0   | chdir           |           | no   |
| 4.0.0   | dirname         |           | no   |
| 4.0.0   | realpath        |           | no   |
| 4.0.0   | error_reporting |           | no   |
| 4.0.0   | ini_set         |           | no   |
| 4.0.0   | var_dump        |           | no   |
| 4.0.0   | get_object_vars |           | no   |
| 5.1.0   | property_exists |           | no   |
+---------+-----------------+-----------+------+
  • Level 5 is equivalent to level 4 + level 1 + level 0.
  • Level 6 is equivalent to level 4 + level 2.
  • Level 7 is equivalent to level 4 + level 2 + level 1.
-n | --no-recurse

pci -n -d directory

Runs the parser and analyze only files in directory identified by -d or --dir. Default behavior will parse all directory childs recursively.

-if | --ignore-files

Identify the parameter text file that contains on each line the name of each file to ignore when parsing a directory/branch.

Default value used files.txt file in the same directory as pci script.

-id | --ignore-dirs

Identify the parameter text file that contains on each line the name of each sub-directory to ignore when parsing a directory/branch.

Default value used dirs.txt file in the same directory as pci script.

-in | --ignore-functions

Identify the parameter text file that contains on each line the name of each PHP function to ignore when parsing the data source.

Default value used functions.txt file in the same directory as pci script.

-ic | --ignore-constants

Identify the parameter text file that contains on each line the name of each PHP constant to ignore when parsing the data source

Default value used constants.txt file in the same directory as pci script.

-ie | --ignore-extensions

Identify the parameter text file that contains on each line the name of each PHP extension to ignore (all extension.functions) when parsing the data source

-iv | --ignore-versions

Expect one or two values that identify which PHP version (and all its related functions) to ignore.

For example: ignore all PHP 5 functions (minor releases 0 thru 2), or only PHP 5.0.0 functions. pci -f file -iv 5.0.0 5.2.0 pci -d directory -iv 5.0.0

-inm | --ignore-functions-match

Identify the parameter text file that contains on each line a pattern (match a regular expression) of PHP function to ignore when parsing the data source.

Default value used functions-match.txt file in the same directory as pci script.

Comments start with ";", as in php.ini, and blank lines are allowed.

If you want to use the preg_match compare function, put a "=", to start the line, follow by a regular expression.

-iem | --ignore-extensions-match

Identify the parameter text file that contains on each line a pattern (match a regular expression) of PHP extension to ignore when parsing the data source.

Default value used extensions-match.txt file in the same directory as pci script.

Comments start with ";", as in php.ini, and blank lines are allowed.

If you want to use the preg_match compare function, put a "=", to start the line, follow by a regular expression.

-icm | --ignore-constants-match

Identify the parameter text file that contains on each line a pattern (match a regular expression) of PHP constant to ignore when parsing a directory, a single file, or a string.

Default value used constants-match.txt file in the same directory as pci script.

Comments start with ";", as in php.ini, and blank lines are allowed.

If you want to use the preg_match compare function, put a "=", to start the line, follow by a regular expression.

-fe | --file-ext

Follow by a comma separated list of file extensions to parse (only valid if parsing a directory). Default is: php,php4,inc,phtml

-r | --report

Print either a text report (default), or any others render available (csv, xml, ...)

For example: pci -r xml -f /tmp/PHP_CodeSniffer-1.1.0/CodeSniffer.php give these results (when package XML_Beautifier is available)

       
<?xml version="1.0" encoding="UTF-8"?>
<pci version="1.9.0b2">
    <file name="/tmp/PHP_CodeSniffer-1.1.0/CodeSniffer.php">
    <version>5.1.2</version>
    <conditions level="0" />
    <extensions count="5">
        <extension>date</extension>
        <extension>pcre</extension>
        <extension>SPL</extension>
        <extension>tokenizer</extension>
        <extension>xml</extension>
    </extensions>
    <constants count="7">
        <constant>DIRECTORY_SEPARATOR</constant>
        <constant>FALSE</constant>
        <constant>NULL</constant>
        <constant>PHP_EOL</constant>
        <constant>TRUE</constant>
        <constant>T_STRING</constant>
        <constant>__FILE__</constant>
    </constants>
    <tokens count="5">
        <token>catch</token>
        <token>protected</token>
        <token>public</token>
        <token>throw</token>
        <token>try</token>
    </tokens>
    <ignored>
        <files count="0" />
        <functions count="0" />
        <extensions count="0" />
        <constants count="0" />
    </ignored>
</pci>
       

And with little debug option ( verbose level 4 ) pci -r xml -v 4 -f /tmp/PHP_CodeSniffer-1.1.0/CodeSniffer.php results became

       
<?xml version="1.0" encoding="UTF-8"?>
<pci version="1.9.0b2">
    <file>/tmp/PHP_CodeSniffer-1.1.0/CodeSniffer.php</file>
    <version>5.1.2</version>
    <conditions count="0" level="0" />
    <extensions count="5">
        <extension>date</extension>
        <extension>pcre</extension>
        <extension>SPL</extension>
        <extension>tokenizer</extension>
        <extension>xml</extension>
    </extensions>
    <constants count="7">
        <constant>DIRECTORY_SEPARATOR</constant>
        <constant>FALSE</constant>
        <constant>NULL</constant>
        <constant>PHP_EOL</constant>
        <constant>TRUE</constant>
        <constant>T_STRING</constant>
        <constant>__FILE__</constant>
    </constants>
    <tokens count="5">
        <token>catch</token>
        <token>protected</token>
        <token>public</token>
        <token>throw</token>
        <token>try</token>
    </tokens>
    <ignored>
        <files count="0" />
        <functions count="0" />
        <extensions count="0" />
        <constants count="0" />
    </ignored>
    <functions count="41">
        <function version="4.0.0">class_exists</function>
        <function version="4.0.0">define</function>
        <function version="4.0.0">chdir</function>
        <function version="4.0.0">dirname</function>
        <function version="4.0.0">substr</function>
        <function version="4.0.0">str_replace</function>
        <function version="4.0.0">is_file</function>
        <function version="4.0.0">is_array</function>
        <function version="4.0.0">is_string</function>
        <function version="4.0.0">count</function>
        <function version="4.0.0">is_dir</function>
        <function version="4.0.0">basename</function>
        <function version="4.0.0">realpath</function>
        <function version="4.0.0">strtolower</function>
        <function version="4.0.0">strrpos</function>
        <function version="4.0.0">in_array</function>
        <function version="4.0.0">explode</function>
        <function version="4.0.0">array_pop</function>
        <function version="4.0.0">array_merge</function>
        <function version="4.0.0">file_exists</function>
        <function version="4.0.0">strtr</function>
        <function extension="pcre" pecl="false" version="4.0.0">preg_match</function>
        <function extension="date" pecl="false" version="4.0.0">time</function>
        <function version="4.0.0">ksort</function>
        <function version="4.0.0">htmlspecialchars</function>
        <function extension="xml" pecl="false" version="4.0.0">utf8_encode</function>
        <function version="4.0.0">strlen</function>
        <function version="4.0.0">str_repeat</function>
        <function version="4.0.0">ord</function>
        <function version="4.0.0">strtoupper</function>
        <function version="4.0.0">strpos</function>
        <function version="4.0.0">rtrim</function>
        <function version="4.0.0">is_writable</function>
        <function version="4.0.2">wordwrap</function>
        <function version="4.0.4">is_null</function>
        <function version="4.0.4">constant</function>
        <function extension="tokenizer" pecl="false" version="4.2.0">token_name</function>
        <function version="4.2.0">var_export</function>
        <function version="5.0.0">file_put_contents</function>
        <function version="5.0.2">interface_exists</function>
        <function extension="SPL" pecl="false" version="5.1.2">spl_autoload_register</function>
    </functions>
</pci>
       
-o | --output-level

Allow to filter data type (column) you want on standard output (console). From all details (31=default) to only file name (=0)

  • 0: file name
  • 1: conditional code
  • 2: extensions
  • 4: constants
  • 8: tokens
  • 16: version

output_level is binary value. So to have, for example, only file name (always mandatory) with version and extensions, you have to give value 18 (16 + 2).

-t | --tab

Sets the Files, Etensions and Constants/Tokens columns width. Default values are: 29 char. for Files colum, 12 char. for Extentions column, and 20 char. for Constants/Tokens column.

Here are the best values optimized by output-level for a 80 columns screen width, to almost always see extensions and constants/tokens without name truncated: first value is always for Files column (f), second value is always for Extensions column (e), and third value is always for Constants/Tokens column (c)

If a (f,e,c) value is missing then the corresponding default value (f=29,e=12,c=20) is used.

For example: 56,,20 is equivalent to 56,12,20

  • output-level 0: 77
  • output-level 1: 73
  • output-level 2: 59,17
  • output-level 3: 55,17
  • output-level 4, 8, 12: 55,,21
  • output-level 5, 9, 13: 51,,21
  • output-level 6, 10, 14: 37,17,21
  • output-level 7, 11, 15: 33,17,21
  • output-level 16: 67
  • output-level 17: 63
  • output-level 18: 49,17
  • output-level 19: 45,17
  • output-level 20, 24: 45,,21
  • output-level 21, 25, 29: 41,,21
  • output-level 22, 26, 30: 27,17,21
  • output-level 23, 27, 31: 23,17,21
  • output-level 24, 28: 45,17,21
-p | --progress [ bar | text ]

Show a progress bar (if PEAR::Console_ProgressBar is installed) or a simple text wait message when parsing a directory.

If you specify --progress bar and PEAR::Console_ProgressBar is not available, then default display will be text wait message (without giving an error), as if you have specified --progress text instead

-S | --summarize

Print only the summary of parsing result for a directory, rather than full details file by file (default).

-V | --version

Print only the current version information

-h | --help

Show help panel (as described in beginning of this section)

Display results

Let's take a look now at the result displayed : the main table

+-----------------------------+---------+---+------------+--------------------+
| Files                       | Version | C | Extensions | Constants/Tokens   |
+-----------------------------+---------+---+------------+--------------------+

+-----------------------------+---------+---+------------+--------------------+

We have, by default (output-level = 31) 5 columns

For Files, Extensions, Constants/Tokens columns, if content is larger than cell width, then the content if truncated by left, and replaced by ...

When verbose mode is set to level 1, you have an additional table displayed, that resume the command line arguments

Command Line resume :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+

+-------------------------+---------------------------------------------------+

When verbose mode is set to level 2, you have an additional table displayed, that resume the parser options used

Parser options :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+

+-------------------------+---------------------------------------------------+

When verbose mode is set to level 4, you have an additional table displayed, that show each PHP standard or PECL functions with their version

Debug:

+---------+-----------------+-----------+------+
| Version | Function        | Extension | PECL |
+---------+-----------------+-----------+------+

+---------+-----------------+-----------+------+

Outputting Results

Outputting Results – how to use the renderer system

Overview

PHP_CompatInfo can use different kind of renderers and provides a default one (Array) which print a complete parsable string representation of results.

There are 6 renderers available with PHP_CompatInfo 1.8.0

If none of them match your need, you can also write your own renderers.

Basic usage

The main steps of using any available renderer are quite similar:

<?php
require_once 'PHP/CompatInfo.php';

// data source to parse: file, directory, string, ...
$datasource = '/tmp/HTML_CSS-1.5.1';

// parser options depending of data source
$options    = array();

// kind of renderer: array, csv, html, null, text, xml, ...
$driverType    = 'array';  // case insensitive

// specific renderer hash options
$driverOptions = array();

$pci = new PHP_CompatInfo($driverType, $driverOptions);
$r = $pci->parseData($datasource, $options);
?>

To keep compatibility with previous versions, you can find the result similar to var_export (Array renderer) in $r (in our example). All parse functions (parseDir, parseFile, parseArray, parseString) have the same behavior.

PHP_CompatInfo class constructor expect to receive two parameters: first one identify the kind of renderer (array, csv, html, null, text, xml), while second is private and specific to each renderer. Allows to customize a bit the renderer without to rewrite a new one (explore all options before beginning to write your own version).

Configuration options

Before to have a look on each driver specific options, take a short pause on common options of all renderers.

All renderers can be run in both interfaces (web and cli), this is why we can find a hash named args in the driver array options (second parameter of PHP_CompatInfo class constructor). This hash replace corresponding arguments you should have (otherwise) to specify on the Command-Line.

Array renderer options

Array renderer used two drivers to show dump of results. Default is PHP (var_export function). The other one is PEAR::Var_Dump. You can use this last one only if package is installed on your system.

While there are no specific options for PHP driver, you can use all options of PEAR::Var_Dump to beautify the dump of results. See example docs/examples/pci180_parsefile.php in the package distribution.

First key of hash (options) allow to choose the Var_Dump renderer (display_mode) you want.

Only display_mode = Text is allowed if you run PHP_CompatInfo on CLI.

Second key of hash (rendererOptions) allow to give specific options to the Var_Dump renderer identified by display_mode directive.

Var_Dump package exists for two major versions of PHP.

Var_Dump PHP 4 on default PEAR channel (branch 1.0)

Var_Dump PHP 5 on PEAR channel Toolbox (branch 1.2)

Csv renderer options

Csv renderer can be customized only in one way: change delimiters characters

Html renderer options

Html renderer have only one specific option :

See also the docs/examples/pci180_parsedir_tohtml.php example in the package distribution, howto define your own html renderer.

Text renderer options

Text renderer have only one specific option :

See the Command-Line Parser section, and -t | --tab switch to learn more about optimized values depending of output-level

Xml renderer options

Xml renderer have only two specific options :

Use no value if you have PEAR::XML_Beautifier installed, and you don't want to have XML beautified.

See also the docs/examples/pci180_parsedata_toxml.php, and docs/examples/pci180_parsestring_toxml.php examples in the package distribution.

Build your Extension Support List

Build your Extension Support List – or how to improve detection

Why a new API ?

Since version 1.0.1 and until version 1.9.0, PHP_CompatInfo (aka PCI) used only one monolithic file for all functions, and another one for all constants. These 2 file support both standard (PHP core) and all extensions known (or supposed to be). This system was the first fruits to a dictionary system with the limitation we know now.

Bug report 15011 help me to think again on a new way to improve the dictionary system without any limitation.

As I can't provide all extensions support (already known or future), the new architecture named Extension Support List (aka ESL) will have by default a group of dictionary that know elements of 25 common extensions. But I will let ability to end-users to build their own ESL corresponding to their platform.

Concept was born.

PCI provide an automated system named pciconf (PHP5 CLI script) to build all dictionaries required. Of course, as I didn't want to let down PHP4 users, I will propose two different ways to update your ESL: a first for PHP4 (alternative), and a second for PHP5 (recommanded). But before to explain how to do it, have a look on dictionary structure.

Data Dictionaries

There are 3 main data dictionary knew only by the PCI core of version 1.9.0+. Each one identify a list (alphabetical sorted order) of basic extension component.

Each extension should have (normally) at least a function dictionary (required), but may also have a class and/or constant dictionary (optional) depending of informations it provided. For example: Take the Libxml that contains 3 types of data dictionary.

All extensions data dictionary is a key-values pair array, with name of function, constant or class, as the key, and specific data as the values.

Specific data is also an array with key-value pairs. Constant and Class dictionary required only 2 keys: init, and name, while Function dictionary required at least 3 keys: init, ext and pecl.

init

the first PHP version which extension element (function, constant, class) came from

end

the last PHP version which extension element (function, constant, class) is available

name

name of extension element (function, constant, class)

ext

name of extension (case sensitive)

ext

tell if extension came from PECL repository or not

Procedure to build your ESL for PHP4 users

This procedure is also named alternative solution, because it's manual. You make changes at your own risks.

If you need only extension included in the default distribution, the solution is easy. Edit by hand the global dictionaries, add resources required and add extension dict to the list as follow : Suppose we need support of XSL extension.

That's all. Your PCI system is ready to detect all data sources that used the XSL extension.

Procedure to build your ESL for PHP5 users

This procedure is also named recommanded solution, because there are no manual changes. But for technical reasons, it's only available for PHP5+ users.

PCI provide an automated system named pciconf. This CLI script allow to:

That's all. Your PCI system is ready to detect all data sources that used extension(s) you have choosen.

You cannot build dictionary for an extension that is not installed on your platform. Unless you used the PHP4 alternative solution.

Build your Exception Rules System

Build your Exception Rules System – or how to fix invalid values

Who need to fix error ?

Since version 1.9.0, PHP_CompatInfo (aka PCI) used a full data dictionary system based on source files (set of versions.xml) used by the PHP Manual generation itself.

Of course, if extensions files reference (of phpdoc) changed, you have to wait a new release of PCI to see bugs/changes fixed.

If you can't wait a new PCI release, or because reference (phpdoc) files are fake and not yet fixed, there is an alternative solution named Exception Rules System (aka ERS).

Procedure to build your ERS for PHP4 users

This procedure is not secure, because you can lose your changes if you install a new PCI release that did not included your fixes.

End-users have to fix the wrong values in data dictionaries themself (by hand).

Procedure to build your ERS for PHP5 users

This procedure is pretty secure, and minimize risk to lose informations.

Version 1.9.0 of PCI used itself the ERS to fix data still missing in phpdoc reference.

Reason: Migration from monolithic http://cvs.php.net/viewvc.cgi/phpdoc/phpbook/phpbook-xsl/version.xml to specific extension file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/*/version.xml is not yet over !

pciconf CLI script build data dictionary from source below :

  1. the phpdoc reference mirror files installed in PCI data directory @data_dir@/PHP_CompatInfo/data/phpdocref/, where @data_dir@ identify your PEAR data directory.
  2. a list of Exception Rules installed in @php_dir@/scripts/pciconf/, where @php_dir@ identify your PEAR directory.

Default Exception Rules are provided by a set of file s named *_func_exception.php, *_const_exception.php, *_class_exception.php, where * means for the extension name (case sensitive).

Exception Rules files have the same structure as data dictionary. Only the array php variable name is different.

pciconf detect presence of Exception Rules by the exceptions.conf.php file.

This file implement a required function

mixed getExceptions ( string $extension , string $type )

First argument $extension identify the extension name, while second argument $type identify the kind of exception (version, class, function, constant) to proceed.

If function return FALSE, that means there are no value to apply/merge with the phpdoc base reference. Otherwise, function should return a compatible data dictionary structure (array) what contains all news/changes to apply.

To use your own ERS, you have to tell it to the pciconf script with the --exception switch.

Example: pciconf --exception /home/users/farell/myERS.php

In summary:

Reference guide

PHP version history

PHP_CompatInfo::loadVersion

PHP_CompatInfo::loadVersion() – Load components list

Synopsis
require_once 'PHP/CompatInfo.php';

array PHP_CompatInfo::loadVersion ( string $min , string|boolean $max = false , boolean $include_const = false , boolean $groupby_vers = false )

Description

Load components list for a PHP version or subset

Parameter
string $min

PHP minimal version

string|boolean $max

(optional) PHP maximal version

boolean $include_const

(optional) include constants list in final result

boolean $groupby_vers

(optional) give initial php version of function or constant

Return value

returns An array of php function available in version(s) given

returns A mixed array of php function + php constants available in version(s) given. Available with parameter #3 ($include_const) since API 1.6.0

Throws

throws no exceptions thrown

Since

since version 1.2.0 (2006-08-23)

Note

This function can not be called statically.

Example

What's new with PHP version 4.3.10 ?

<?php
require_once 'PHP/CompatInfo.php';

$pci = new PHP_CompatInfo();
$res = $pci->loadVersion('4.3.10', '4.3.10', true);
var_export($res);
?>

Result give: 0 function and 2 constants

array (
  'functions' =>
  array (
  ),
  'constants' =>
  array (
    0 => 'PHP_EOL',
    1 => 'UPLOAD_ERR_NO_TMP_DIR',
  ),
)

What's new since PHP version 5.2.1 ?

<?php
require_once 'PHP/CompatInfo.php';

$pci = new PHP_CompatInfo();
$res = $pci->loadVersion('5.2.1');
var_export($res);
?>

Result give only 4 functions (with default Extension Support List provided by version 1.9.0 of PHP_CompatInfo). Depending of your Extension Support List, this result can be different.

array (
  0 => 'php_ini_loaded_file',
  1 => 'stream_is_local',
  2 => 'stream_socket_shutdown',
  3 => 'sys_get_temp_dir',
)

Observers

PHP_CompatInfo::addListener

PHP_CompatInfo::addListener() – Registers a new listener

Synopsis
require_once 'PHP/CompatInfo.php';

void PHP_CompatInfo::addListener ( mixed $callback , string $nName = EVENT_DISPATCHER_GLOBAL )

Description

Registers a new listener with the given criteria

Parameter
mixed $callback

A PHP callback

string $nName

(optional) Expected notification name

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b3 (2008-06-07)

Note

This function can not be called statically.

Example

Attach a simple function that will listen all PHP_CompatInfo events, which write start and end audit results in a flat file defined by a php constant.

<?php
require_once 'PHP/CompatInfo.php';

define('DEST_PCI_LOG', '/var/log/pciEvents.log');

function debugNotify(&$auditEvent)
{
    $notifyName = $auditEvent->getNotificationName();
    $notifyInfo = $auditEvent->getNotificationInfo();

    if ($notifyName == PHP_COMPATINFO_EVENT_AUDITSTARTED) {
        error_log($notifyName.':'. PHP_EOL .
                  var_export($notifyInfo, true) . PHP_EOL,
                  3, DEST_PCI_LOG);

    } elseif ($notifyName == PHP_COMPATINFO_EVENT_AUDITFINISHED) {
        error_log($notifyName.':'. PHP_EOL .
                  var_export($notifyInfo, true) . PHP_EOL,
                  3, DEST_PCI_LOG);
    }
}

$cbObserver = 'debugNotify';

$pci = new PHP_CompatInfo();
$pci->addListener($cbObserver);
// ...
$source  = '';      // <- identify the date source to parse
$options = array(); // <- some parser options

$pci->parseData($source, $options);

$pci->removeListener($cbObserver);
?>

PHP_CompatInfo::removeListener

PHP_CompatInfo::removeListener() – Removes a registered listener

Synopsis
require_once 'PHP/CompatInfo.php';

bool PHP_CompatInfo::removeListener ( mixed $callback , string $nName = EVENT_DISPATCHER_GLOBAL )

Description

Removes a registered listener that correspond to the given criteria.

Parameter
mixed $callback

A PHP callback

string $nName

(optional) Expected notification name

Return value

returns True if listener was removed, false otherwise.

Throws

throws no exceptions thrown

Since

since version 1.8.0b3 (2008-06-07)

Note

This function can not be called statically.

Example

see PHP_CompatInfo::addListener() example

Parsing Data Sources

PHP_CompatInfo::parseArray

PHP_CompatInfo::parseArray() – Parse an Array of Files

Synopsis
require_once 'PHP/CompatInfo.php';

array|false PHP_CompatInfo::parseArray ( array $files , array $options = array() )

Description

You can parse an array of Files or Strings. To parse strings, $options['is_string'] must be set to true

Parameter
array $files

Array of file names or code strings

array $options

An array of options where:

  • file_ext Contains an array of file extensions to parse for PHP code. Default: php, php4, inc, phtml
  • debug Contains a boolean to control whether extra ouput is shown.
  • ignore_functions Contains an array of functions to ignore when calculating the version needed.
  • ignore_constants Contains an array of constants to ignore when calculating the version needed.
  • ignore_files Contains an array of files to ignore. File names are case insensitive.
  • is_string Contains a boolean which says if the array values are strings or file names.
  • ignore_extensions Contains an array of php extensions to ignore when calculating the version needed.
  • ignore_versions Contains an array of php versions to ignore when calculating the version needed.
  • ignore_functions_match Contains an array of function patterns to ignore when calculating the version needed.
  • ignore_extensions_match Contains an array of extension patterns to ignore when calculating the version needed.
  • ignore_constants_match Contains an array of constant patterns to ignore when calculating the version needed.
Throws

throws no exceptions thrown

See

see PHP_CompatInfo::parseData()

Since

since version 0.7.0 (2004-03-09)

Note

This function can not be called statically.

Return value

array - a hash which contains information keys: ignored_functions, ignored_extensions, ignored_constants, max_version, version, extensions, constants, tokens, cond_code

Example
<?php
require_once 'PHP/CompatInfo.php';

$pci = new PHP_CompatInfo();

$input = array('/opt/lampp/etc/pear/PEAR.php',
               '/opt/lampp/etc/pear/PHP/CompatInfo.php');

$res = $pci->parseArray($input);

#var_export($res); // no need since PCI 1.8.0
?>

We get such result.

array (
  'ignored_files' =>
  array (
  ),
  'ignored_functions' =>
  array (
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '4.3.0',
  'classes' =>
  array (
    0 => 'PHP_CompatInfo_Parser',
  ),
  'extensions' =>
  array (
    0 => 'pcre',
    1 => 'tokenizer',
  ),
  'constants' =>
  array (
    0 => 'E_USER_ERROR',
    1 => 'E_USER_NOTICE',
    2 => 'E_USER_WARNING',
    3 => 'FALSE',
    4 => 'NULL',
    5 => 'PHP_OS',
    6 => 'PHP_VERSION',
    7 => 'TRUE',
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 5,
  ),
  '/opt/lampp/etc/pear/PEAR.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.3.0',
    'classes' =>
    array (
    ),
    'extensions' =>
    array (
    ),
    'constants' =>
    array (
      0 => 'E_USER_ERROR',
      1 => 'E_USER_NOTICE',
      2 => 'E_USER_WARNING',
      3 => 'FALSE',
      4 => 'NULL',
      5 => 'PHP_OS',
      6 => 'PHP_VERSION',
      7 => 'TRUE',
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 5,
    ),
  ),
  '/opt/lampp/etc/pear/PHP/CompatInfo.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.3.0',
    'classes' =>
    array (
      0 => 'PHP_CompatInfo_Parser',
    ),
    'extensions' =>
    array (
      0 => 'pcre',
      1 => 'tokenizer',
    ),
    'constants' =>
    array (
      0 => 'FALSE',
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 0,
    ),
  ),
)

As for parseDir() we have global result, follow by each $input entry result in details.

Either all $input entries are files, or all are string (chunk of php code). You cannot have both (one or more) string and (one or more) file reference.

PHP_CompatInfo::parseDir

PHP_CompatInfo::parseDir() – Parse a directory

Synopsis
require_once 'PHP/CompatInfo.php';

array PHP_CompatInfo::parseDir ( string $dir , array $options = array() )

Description

Parse a directory recursively for its compatibility info

Parameter
string $dir

Path of folder to parse

array $options

An array of options where:

  • file_ext Contains an array of file extensions to parse for PHP code. Default: php, php4, inc, phtml
  • recurse_dir Boolean on whether to recursively find files
  • debug Contains a boolean to control whether extra ouput is shown.
  • ignore_functions Contains an array of functions to ignore when calculating the version needed.
  • ignore_constants Contains an array of constants to ignore when calculating the version needed.
  • ignore_files Contains an array of files to ignore. File names are case insensitive.
  • ignore_dirs Contains an array of directories to ignore. Directory names are case insensitive.
  • ignore_extensions Contains an array of php extensions to ignore when calculating the version needed.
  • ignore_versions Contains an array of php versions to ignore when calculating the version needed.
  • ignore_functions_match Contains an array of function patterns to ignore when calculating the version needed.
  • ignore_extensions_match Contains an array of extension patterns to ignore when calculating the version needed.
  • ignore_constants_match Contains an array of constant patterns to ignore when calculating the version needed.
Throws

throws no exceptions thrown

See

see PHP_CompatInfo::parseFolder() , PHP_CompatInfo::parseData()

Since

since version 0.8.0 (2004-04-22)

Note

This function can not be called statically.

Return value

array - a hash which contains information keys: ignored_functions, ignored_extensions, ignored_constants, max_version, version, extensions, constants, tokens, cond_code

Example

Suppose we have these dirs/files to parse :

PHP_CompatInfo/tests/parseDir/
  PHP5/tokens.php5
  PHP5/upload_error.php
  extensions.php
  phpinfo.php

See package distribution to know in details content of this scripts.

<?php
require_once 'PHP/CompatInfo.php';

$pci = new PHP_CompatInfo();

$input   = 'PHP_CompatInfo/tests/parseDir/';
$options = array('recurse_dir' => true,
                 'file_ext'    => array('php', 'php5')
                );

$res = $pci->parseDir($input, $options);

#var_export($res); // no need since PCI 1.8.0
?>

We get such result.

array (
  'ignored_files' =>
  array (
  ),
  'ignored_functions' =>
  array (
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '5.2.0',
  'classes' =>
  array (
    0 => 'Exception',
  ),
  'extensions' =>
  array (
  ),
  'constants' =>
  array (
    0 => 'PHP_SHLIB_SUFFIX',
    1 => 'TRUE',
    2 => 'UPLOAD_ERR_CANT_WRITE',
    3 => 'UPLOAD_ERR_EXTENSION',
    4 => 'UPLOAD_ERR_FORM_SIZE',
    5 => 'UPLOAD_ERR_INI_SIZE',
    6 => 'UPLOAD_ERR_NO_FILE',
    7 => 'UPLOAD_ERR_NO_TMP_DIR',
    8 => 'UPLOAD_ERR_OK',
    9 => 'UPLOAD_ERR_PARTIAL',
  ),
  'tokens' =>
  array (
    0 => 'abstract',
    1 => 'catch',
    2 => 'clone',
    3 => 'final',
    4 => 'implements',
    5 => 'instanceof',
    6 => 'interface',
    7 => 'private',
    8 => 'protected',
    9 => 'public',
    10 => 'throw',
    11 => 'try',
  ),
  'cond_code' =>
  array (
    0 => 2,
  ),
  'PHP_CompatInfo/tests/parseDir/extensions.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.3.2',
    'classes' =>
    array (
    ),
    'extensions' =>
    array (
    ),
    'constants' =>
    array (
      0 => 'PHP_SHLIB_SUFFIX',
      1 => 'TRUE',
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 2,
    ),
  ),
  'PHP_CompatInfo/tests/parseDir/phpinfo.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.0.0',
    'classes' =>
    array (
    ),
    'extensions' =>
    array (
    ),
    'constants' =>
    array (
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 0,
    ),
  ),
  'PHP_CompatInfo/tests/parseDir/PHP5/tokens.php5' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '5.0.0',
    'classes' =>
    array (
      0 => 'Exception',
    ),
    'extensions' =>
    array (
    ),
    'constants' =>
    array (
    ),
    'tokens' =>
    array (
      0 => 'abstract',
      1 => 'catch',
      2 => 'clone',
      3 => 'final',
      4 => 'implements',
      5 => 'instanceof',
      6 => 'interface',
      7 => 'private',
      8 => 'protected',
      9 => 'public',
      10 => 'throw',
      11 => 'try',
    ),
    'cond_code' =>
    array (
      0 => 0,
    ),
  ),
  'PHP_CompatInfo/tests/parseDir/PHP5/upload_error.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '5.2.0',
    'classes' =>
    array (
      0 => 'Exception',
    ),
    'extensions' =>
    array (
    ),
    'constants' =>
    array (
      0 => 'UPLOAD_ERR_CANT_WRITE',
      1 => 'UPLOAD_ERR_EXTENSION',
      2 => 'UPLOAD_ERR_FORM_SIZE',
      3 => 'UPLOAD_ERR_INI_SIZE',
      4 => 'UPLOAD_ERR_NO_FILE',
      5 => 'UPLOAD_ERR_NO_TMP_DIR',
      6 => 'UPLOAD_ERR_OK',
      7 => 'UPLOAD_ERR_PARTIAL',
    ),
    'tokens' =>
    array (
      0 => 'throw',
    ),
    'cond_code' =>
    array (
      0 => 0,
    ),
  ),
)

We have global result, then follow by each file parsed in sub-directories.

PHP_CompatInfo::parseFolder

PHP_CompatInfo::parseFolder() – Alias of parseDir

Synopsis
require_once 'PHP/CompatInfo.php';

void PHP_CompatInfo::parseFolder ( string $folder , array $options = array() )

Description

Alias of parseDir function

Parameter
string $folder

Path of folder to parse

array $options

An array of options

Throws

throws no exceptions thrown

See

see PHP_CompatInfo::parseDir() , PHP_CompatInfo::parseData()

Since

since version 0.7.0 (2004-03-09)

Note

This function can not be called statically.

Return value

array - a hash which contains information keys: ignored_functions, ignored_extensions, ignored_constants, max_version, version, extensions, constants, tokens, cond_code

Example

See PHP_CompatInfo::parseDir() example.

PHP_CompatInfo::parseFile

PHP_CompatInfo::parseFile() – Parse a single file

Synopsis
require_once 'PHP/CompatInfo.php';

Array PHP_CompatInfo::parseFile ( string $file , array $options = array() )

Description

Parse a file for its compatibility info

Parameter
string $file

Path of File to parse

array $options

An array of options where:

  • debug Contains a boolean to control whether extra ouput is shown.
  • ignore_functions Contains an array of functions to ignore when calculating the version needed.
  • ignore_constants Contains an array of constants to ignore when calculating the version needed.
  • ignore_extensions Contains an array of php extensions to ignore when calculating the version needed.
  • ignore_versions Contains an array of php versions to ignore when calculating the version needed.
  • ignore_functions_match Contains an array of function patterns to ignore when calculating the version needed.
  • ignore_extensions_match Contains an array of extension patterns to ignore when calculating the version needed.
  • ignore_constants_match Contains an array of constant patterns to ignore when calculating the version needed.
Throws

throws no exceptions thrown

See

see PHP_CompatInfo::parseData()

Since

since version 0.7.0 (2004-03-09)

Note

This function can not be called statically.

Return value

array - a hash which contains information keys: ignored_functions, ignored_extensions, ignored_constants, max_version, version, extensions, constants, tokens, cond_code

Example

Suppose we have to parse source code like this one, named "conditional.php" :

<?php
// PHP 4.0.0 : __FILE__
// PHP 4.0.6 : DIRECTORY_SEPARATOR
// PHP 4.0.7 : version compare
// PHP 4.3.0 : ob_get_clean
// PHP 4.3.0 : debug_backtrace
// PHP 4.3.10 and 5.0.2 : PHP_EOL
// PHP 5.0.0 : simplexml_load_file
// PHP 5.1.1 : DATE_W3C

if (!defined('DIRECTORY_SEPARATOR')) {
    define('DIRECTORY_SEPARATOR',
        strtoupper(substr(PHP_OS, 0, 3) == 'WIN') ? '\\' : '/'
    );
}

if (function_exists('debug_backtrace')) {
    $backtrace = debug_backtrace();
} else {
    $backtrace = false;
}

if (function_exists('simplexml_load_file')) {
    $xml = simplexml_load_file('C:\php\pear\PHP_CompatInfo\scripts\version.xml');
}

if (version_compare(phpversion(), '5.0.0', '<')) {
    include_once 'PHP/Compat.php';
    PHP_Compat::loadFunction('ob_get_clean');
    PHP_Compat::loadConstant('PHP_EOL');
}

echo "Hello World" . PHP_EOL;

$ds  = DIRECTORY_SEPARATOR;
$fn  = dirname(__FILE__) . $ds . basename(__FILE__);
echo "You have run file : $fn at " . date(DATE_W3C) . PHP_EOL;

?>
<?php
require_once 'PHP/CompatInfo.php';

$pci = new PHP_CompatInfo();

$input   = 'conditional.php';
$options = array('ignore_functions' => array('simplexml_load_file'),
                 'ignore_constants' => array('DATE_W3C')
                );

$res = $pci->parseFile($input, $options);

#var_export($res); // no need since PCI 1.8.0
?>

We get such result.

array (
  'ignored_functions' =>
  array (
    0 => 'simplexml_load_file',
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
    0 => 'DATE_W3C',
  ),
  'max_version' => '',
  'version' => '4.3.10',
  'classes' =>
  array (
  ),
  'extensions' =>
  array (
    0 => 'date',
  ),
  'constants' =>
  array (
    0 => 'DATE_W3C',
    1 => 'DIRECTORY_SEPARATOR',
    2 => 'FALSE',
    3 => 'PHP_EOL',
    4 => 'PHP_OS',
    5 => '__FILE__',
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 5,
  ),
)

That means php simple_load_file() function and constant DATE_W3C were ignored from scope, and PHP version minimum to run is 4.3.10 (in such condition)

Of course it is impossible to run such script with only PHP 4.3.10 because usage of DATE_W3C constant is not conditionned.

PHP_CompatInfo::parseString

PHP_CompatInfo::parseString() – Parse a string

Synopsis
require_once 'PHP/CompatInfo.php';

Array PHP_CompatInfo::parseString ( string $string , array $options = array() )

Description

Parse a string for its compatibility info

Parameter
string $string

PHP Code to parses

array $options

An array of options where:

  • debug Contains a boolean to control whether extra ouput is shown.
  • ignore_functions Contains an array of functions to ignore when calculating the version needed.
  • ignore_constants Contains an array of constants to ignore when calculating the version needed.
  • ignore_extensions Contains an array of php extensions to ignore when calculating the version needed.
  • ignore_versions Contains an array of php versions to ignore when calculating the version needed.
  • ignore_functions_match Contains an array of function patterns to ignore when calculating the version needed.
  • ignore_extensions_match Contains an array of extension patterns to ignore when calculating the version needed.
  • ignore_constants_match Contains an array of constant patterns to ignore when calculating the version needed.
Throws

throws no exceptions thrown

See

see PHP_CompatInfo::parseData()

Since

since version 0.7.0 (2004-03-09)

Note

This function can not be called statically.

Return value

array - a hash which contains information keys: ignored_functions, ignored_extensions, ignored_constants, max_version, version, extensions, constants, tokens, cond_code

Example
<?php
require_once 'PHP/CompatInfo.php';

$pci = new PHP_CompatInfo();

$input = '<?php
$nl = "\n";
echo "$nl Rfc3339 = " . DATE_RFC3339;
echo "$nl RSS     = " . DATE_RSS;
?>';

$res = $pci->parseString($input);

#var_export($res); // no need since PCI 1.8.0
?>

We get such result.

array (
  'ignored_functions' =>
  array (
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '5.1.3',
  'classes' =>
  array (
  ),
  'extensions' =>
  array (
  ),
  'constants' =>
  array (
    0 => 'DATE_RFC3339',
    1 => 'DATE_RSS',
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 0,
  ),
)

That means we need PHP 5.1.3 minimum to run this chunk of code, due to usage of DATE_RFC3339 constant.

PHP_CompatInfo::parseData

PHP_CompatInfo::parseData() – Parse a data source

Synopsis
require_once 'PHP/CompatInfo.php';

Array PHP_CompatInfo::parseData ( mixed $dataSource , array $options = array() )

Description

Parse a data source with auto detect ability. This data source, may be one of these follows: a directory, a file, a string (chunk of code), an array of multiple origin.

Parameter
mixed $dataSource

Identify the data source(s)

array $options

An array of common options where:

  • debug Contains a boolean to control whether extra ouput is shown.
  • ignore_functions Contains an array of functions to ignore when calculating the version needed.
  • ignore_constants Contains an array of constants to ignore when calculating the version needed.
  • ignore_extensions Contains an array of php extensions to ignore when calculating the version needed.
  • ignore_versions Contains an array of php versions to ignore when calculating the version needed.
  • ignore_functions_match Contains an array of function patterns to ignore when calculating the version needed.
  • ignore_extensions_match Contains an array of extension patterns to ignore when calculating the version needed.
  • ignore_constants_match Contains an array of constant patterns to ignore when calculating the version needed.

An array of specific options, for parseArray parseDir or parseFolder, where:

  • file_ext Contains an array of file extensions to parse for PHP code. Default: php, php4, inc, phtml
  • ignore_files Contains an array of files to ignore. File names are case insensitive.

An array of specific options, for parseArray, where:

  • is_string Contains a boolean which says if the array values are strings or file names.

An array of specific options, for parseDir or parseFolder, where:

  • recurse_dir Boolean on whether to recursively find files
  • ignore_dirs Contains an array of directories to ignore. Directory names are case insensitive.
Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

Return value

array - a hash which contains information keys: ignored_files, ignored_functions, ignored_extensions, ignored_constants, max_version, version, extensions, constants, tokens, cond_code or FALSE on error.

Example
<?php
require_once 'PHP/CompatInfo.php';

$source  = '/tmp/File_Find-1.3.0/Find.php';
$options = array('debug' => true);

$pci = new PHP_CompatInfo();
$pci->parseData($source, $options);
?>

Getting Results

PHP_CompatInfo::getVersion

PHP_CompatInfo::getVersion() – Returns the latest parse data source version

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getVersion ( mixed $file = false , bool $max = false )

Description

Returns the latest parse data source version, minimum and/or maximum

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

boolean $max

(optional) Level with or without contextual data

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b1 (2008-11-30)

Note

This function can not be called statically.

Example

Suppose we have to parse source code like this file, named "conditional.php" :

<?php
// PHP 4.0.0 : __FILE__
// PHP 4.0.6 : DIRECTORY_SEPARATOR
// PHP 4.0.7 : version compare
// PHP 4.3.0 : ob_get_clean
// PHP 4.3.0 : debug_backtrace
// PHP 4.3.10 and 5.0.2 : PHP_EOL
// PHP 5.0.0 : simplexml_load_file
// PHP 5.1.1 : DATE_W3C

if (!defined('DIRECTORY_SEPARATOR')) {
    define('DIRECTORY_SEPARATOR',
        strtoupper(substr(PHP_OS, 0, 3) == 'WIN') ? '\\' : '/'
    );
}

if (function_exists('debug_backtrace')) {
    $backtrace = debug_backtrace();
} else {
    $backtrace = false;
}

if (function_exists('simplexml_load_file')) {
    $xml = simplexml_load_file('C:\php\pear\PHP_CompatInfo\scripts\version.xml');
}

if (version_compare(phpversion(), '5.0.0', '<')) {
    include_once 'PHP/Compat.php';
    PHP_Compat::loadFunction('ob_get_clean');
    PHP_Compat::loadConstant('PHP_EOL');
}

echo "Hello World" . PHP_EOL;

$ds  = DIRECTORY_SEPARATOR;
$fn  = dirname(__FILE__) . $ds . basename(__FILE__);
echo "You have run file : $fn at " . date(DATE_W3C) . PHP_EOL;
?>

And this second file, named "upload_error.php" :

<?php
$uploadErrors = array(
    UPLOAD_ERR_INI_SIZE   => "The uploaded file exceeds the upload_max_filesize directive in php.ini.",
    UPLOAD_ERR_FORM_SIZE  => "The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form.",
    UPLOAD_ERR_PARTIAL    => "The uploaded file was only partially uploaded.",
    UPLOAD_ERR_NO_FILE    => "No file was uploaded.",
    UPLOAD_ERR_NO_TMP_DIR => "Missing a temporary folder.",
    UPLOAD_ERR_CANT_WRITE => "Failed to write file to disk.",
    UPLOAD_ERR_EXTENSION  => "File upload stopped by extension.",
);

$errorCode = $_FILES["myUpload"]["error"];

if ($errorCode !== UPLOAD_ERR_OK) {
    if (isset($uploadErrors[$errorCode])) {
        throw new Exception($uploadErrors[$errorCode]);
    } else {
        throw new Exception("Unknown error uploading file.");
    }
}
?>

Script to parse data source, will look like to:

<?php
require_once 'PHP/CompatInfo.php';

$pci = new PHP_CompatInfo('null');

$dir     = dirname(__FILE__) . DIRECTORY_SEPARATOR;
$input   = array($dir . 'conditional.php', $dir . 'upload_error.php');
$options = array('ignore_functions' => array('simplexml_load_file'),
                 'ignore_constants' => array('DATE_W3C')
                );

$pci->parseData($input, $options);

$version = $pci->getVersion();
echo 'GLOBAL version = '. $version . PHP_EOL;
$version = $pci->getVersion($input[0]);
echo basename($input[0]) . ' version = '. $version . PHP_EOL;

$classes = $pci->getClasses();
echo 'ALL Classes = '. implode(',', $classes) . PHP_EOL;

$functions = $pci->getFunctions();
echo 'ALL Functions = '. implode(',', $functions) . PHP_EOL;

$extensions = $pci->getExtensions();
echo 'ALL Extensions required = '. implode(',', $extensions) . PHP_EOL;

$constants = $pci->getConstants();
echo 'ALL Constants required = '. implode(',', $constants) . PHP_EOL;

$tokens = $pci->getTokens();
echo 'ALL Tokens required = '. implode(',', $tokens) . PHP_EOL;

$conditions = $pci->getConditions(false, true);
echo 'ALL Code Conditions = '. $conditions . PHP_EOL;
$conditions = $pci->getConditions($input[1], true);
echo basename($input[1]) . ' conditions = '. $conditions . PHP_EOL;
?>

We have just used the NULL renderer because we want to organize output results, as below:

GLOBAL version = 5.2.0
conditional.php version = 4.3.10
ALL Classes = Exception
ALL Functions = basename,date,debug_backtrace,define,defined,dirname,function_exists,
phpversion,simplexml_load_file,strtoupper,substr,version_compare
ALL Extensions required = date
ALL Constants required = DATE_W3C,DIRECTORY_SEPARATOR,FALSE,PHP_EOL,PHP_OS,
UPLOAD_ERR_CANT_WRITE,UPLOAD_ERR_EXTENSION,UPLOAD_ERR_FORM_SIZE,UPLOAD_ERR_INI_SIZE,
UPLOAD_ERR_NO_FILE,UPLOAD_ERR_NO_TMP_DIR,UPLOAD_ERR_OK,UPLOAD_ERR_PARTIAL,__FILE__
ALL Tokens required = throw
ALL Code Conditions = 5
upload_error.php conditions = 0

PHP_CompatInfo::getClasses

PHP_CompatInfo::getClasses() – Returns the latest parse data source classes declared

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getClasses ( mixed $file = false )

Description

Returns the latest parse data source classes declared (internal or end-user defined)

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b1 (2008-11-30)

Note

This function can not be called statically.

Example

See PHP_CompatInfo::getVersion() example.

PHP_CompatInfo::getFunctions

PHP_CompatInfo::getFunctions() – Returns the latest parse data source functions declared

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getFunctions ( mixed $file = false )

Description

Returns the latest parse data source functions declared (internal or end-user defined)

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b1 (2008-11-30)

Note

This function can not be called statically.

Example

See PHP_CompatInfo::getVersion() example.

PHP_CompatInfo::getExtensions

PHP_CompatInfo::getExtensions() – Returns the latest parse data source extensions used

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getExtensions ( mixed $file = false )

Description

Returns the latest parse data source extensions used

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b1 (2008-11-30)

Note

This function can not be called statically.

Example

See PHP_CompatInfo::getVersion() example.

PHP_CompatInfo::getConstants

PHP_CompatInfo::getConstants() – Returns the latest parse data source constants declared

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getConstants ( mixed $file = false )

Description

Returns the latest parse data source constants declared (internal or end-user defined)

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b1 (2008-11-30)

Note

This function can not be called statically.

Example

See PHP_CompatInfo::getVersion() example.

PHP_CompatInfo::getTokens

PHP_CompatInfo::getTokens() – Returns the latest parse data source tokens declared

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getTokens ( mixed $file = false )

Description

Returns the latest parse data source PHP5+ tokens declared

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b1 (2008-11-30)

Note

This function can not be called statically.

Example

See PHP_CompatInfo::getVersion() example.

PHP_CompatInfo::getConditions

PHP_CompatInfo::getConditions() – Returns the latest parse data source conditions

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getConditions ( mixed $file = false , bool $levelOnly = false )

Description

Returns the latest parse data source conditions, with or without contextual data

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

boolean $levelOnly

(optional) Level with or without contextual data

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b1 (2008-11-30)

Note

This function can not be called statically.

Example

See PHP_CompatInfo::getVersion() example.

PHP_CompatInfo::getIgnoredFiles

PHP_CompatInfo::getIgnoredFiles() – Returns list of files ignored

Synopsis
require_once 'PHP/CompatInfo.php';

array PHP_CompatInfo::getIgnoredFiles ( )

Description

Returns list of files ignored while parsing directories

Return value

returns or false on error

Throws

throws no exceptions thrown

Since

since version 1.9.0b2 (2008-12-19)

Note

This function can not be called statically.

PHP_CompatInfo::getIgnoredFunctions

PHP_CompatInfo::getIgnoredFunctions() – Returns the latest parse data source ignored functions

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getIgnoredFunctions ( mixed $file = false )

Description

Returns the latest parse data source ignored functions list

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b2 (2008-12-19)

Note

This function can not be called statically.

Example

Suppose we have to parse source code like this file, named "conditional.php" :

<?php
// PHP 4.0.0 : __FILE__
// PHP 4.0.6 : DIRECTORY_SEPARATOR
// PHP 4.0.7 : version compare
// PHP 4.3.0 : ob_get_clean
// PHP 4.3.0 : debug_backtrace
// PHP 4.3.10 and 5.0.2 : PHP_EOL
// PHP 5.0.0 : simplexml_load_file
// PHP 5.1.1 : DATE_W3C

if (!defined('DIRECTORY_SEPARATOR')) {
    define('DIRECTORY_SEPARATOR',
        strtoupper(substr(PHP_OS, 0, 3) == 'WIN') ? '\\' : '/'
    );
}

if (function_exists('debug_backtrace')) {
    $backtrace = debug_backtrace();
} else {
    $backtrace = false;
}

if (function_exists('simplexml_load_file')) {
    $xml = simplexml_load_file('C:\php\pear\PHP_CompatInfo\scripts\version.xml');
}

if (version_compare(phpversion(), '5.0.0', '<')) {
    include_once 'PHP/Compat.php';
    PHP_Compat::loadFunction('ob_get_clean');
    PHP_Compat::loadConstant('PHP_EOL');
}

echo "Hello World" . PHP_EOL;

$ds  = DIRECTORY_SEPARATOR;
$fn  = dirname(__FILE__) . $ds . basename(__FILE__);
echo "You have run file : $fn at " . date(DATE_W3C) . PHP_EOL;
?>

And this other one, named "ignore_functions_match.php"

<?php
function toFile($filename, $data)
{
    if (function_exists('file_put_contents')) {
        file_put_contents($filename, $data);
    } else {
        $file = fopen($filename, 'wb');
        fwrite($file, $data);
        fclose($file);
    }
}

if (function_exists('debug_backtrace')) {
    $backtrace = debug_backtrace();
} else {
    $backtrace = false;
}

debug_print_backtrace();
?>

Script to parse data source, will look like to:

<?php
require_once 'PHP/CompatInfo.php';

$pci = new PHP_CompatInfo('null');

$dir     = dirname(__FILE__) . DIRECTORY_SEPARATOR;
$input   = array($dir . 'conditional.php', $dir . 'ignore_functions_match.php');
$options = array('ignore_functions_match' => array('preg_match', array('/^debug/')),
                 'ignore_constants' => array('DIRECTORY_SEPARATOR')
                );

$pci->parseData($input, $options);

$functions = $pci->getIgnoredFunctions();
echo 'ALL Ignored Functions = '. implode(',', $functions) . PHP_EOL;
$functions = $pci->getIgnoredFunctions($input[0]);
echo basename($input[0]) . ' ignored functions = '. implode(',', $functions) . PHP_EOL;

$extensions = $pci->getIgnoredExtensions();
echo 'ALL Ignored Extensions = '. implode(',', $extensions) . PHP_EOL;

$constants = $pci->getIgnoredConstants();
echo 'ALL Ignored Constants = '. implode(',', $constants) . PHP_EOL;
?>

We have just used the NULL renderer because we want to organize output results, as below:

ALL Ignored Functions = debug_backtrace,debug_print_backtrace
conditional.php ignored functions = debug_backtrace
ALL Ignored Extensions =
ALL Ignored Constants = DIRECTORY_SEPARATOR

PHP_CompatInfo::getIgnoredExtensions

PHP_CompatInfo::getIgnoredExtensions() – Returns the latest parse data source ignored extensions

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getIgnoredExtensions ( mixed $file = false )

Description

Returns the latest parse data source ignored extensions list

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b2 (2008-12-19)

Note

This function can not be called statically.

Example

See PHP_CompatInfo::getIgnoredFunctions() example.

PHP_CompatInfo::getIgnoredConstants

PHP_CompatInfo::getIgnoredConstants() – Returns the latest parse data source ignored constants

Synopsis
require_once 'PHP/CompatInfo.php';

mixed PHP_CompatInfo::getIgnoredConstants ( mixed $file = false )

Description

Returns the latest parse data source ignored constants list

Parameter
mixed $file

(optional) A specific filename or not (FALSE)

Return value

returns Null on error or if there were no previous data parsing

Throws

throws no exceptions thrown

Since

since version 1.9.0b2 (2008-12-19)

Note

This function can not be called statically.

Example

See PHP_CompatInfo::getIgnoredFunctions() example.

PHP_CompatInfo::getSummary

PHP_CompatInfo::getSummary() – Returns the summary of parsing info

Synopsis
require_once 'PHP/CompatInfo.php';

array PHP_CompatInfo::getSummary ( )

Description

Returns only summary when parsing a directory or multiple data sources

Return value

returns Array of summary results

Throws

throws no exceptions thrown

Since

since version 1.9.0 (2009-01-19)

Note

This function can not be called statically.

Parser Infrastructure

constructor PHP_CompatInfo_Parser::PHP_CompatInfo_Parser

constructor PHP_CompatInfo_Parser::PHP_CompatInfo_Parser() – Parser Class constructor

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

void constructor PHP_CompatInfo_Parser::PHP_CompatInfo_Parser ( )

Description

Parser Class constructor

Return value

returns instance of object PHP_CompatInfo_Parser

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Parser::setOutputDriver

PHP_CompatInfo_Parser::setOutputDriver() – Set up driver to be used

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

void PHP_CompatInfo_Parser::setOutputDriver ( string $type , array $conf = array() )

Description

Set up driver to be used, dependant on specified type.

Parameter
string $type

Name the type of driver (html, text...)

array $conf

A hash containing any additional configuration

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Parser::addListener

PHP_CompatInfo_Parser::addListener() – Registers a new listener

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

void PHP_CompatInfo_Parser::addListener ( mixed $callback , string $nName = EVENT_DISPATCHER_GLOBAL )

Description

Registers a new listener with the given criteria.

Parameter
mixed $callback

A PHP callback

string $nName

(optional) Expected notification name

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

Example

see PHP_CompatInfo::addListener() example

PHP_CompatInfo_Parser::removeListener

PHP_CompatInfo_Parser::removeListener() – Removes a registered listener

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

bool PHP_CompatInfo_Parser::removeListener ( mixed $callback , string $nName = EVENT_DISPATCHER_GLOBAL )

Description

Removes a registered listener that correspond to the given criteria.

Parameter
mixed $callback

A PHP callback

string $nName

(optional) Expected notification name

Return value

returns True if listener was removed, false otherwise.

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

Example

see PHP_CompatInfo::addListener() example

PHP_CompatInfo_Parser::notifyListeners

PHP_CompatInfo_Parser::notifyListeners() – Post a new notification to all listeners registered

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

void PHP_CompatInfo_Parser::notifyListeners ( string $event , array $info = array() )

Description

This notification occured only if a dispatcher exists. That means if at least one listener was registered.

Parameter
string $event

Name of the notification handler

array $info

(optional) Additional information about the notification

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Parser::loadVersion

PHP_CompatInfo_Parser::loadVersion() – Load components list

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

array PHP_CompatInfo_Parser::loadVersion ( string $min , string|boolean $max = false , boolean $include_const = false , boolean $groupby_vers = false )

Description

Load components list for a PHP version or subset

Parameter
string $min

PHP minimal version

string|boolean $max

(optional) PHP maximal version

boolean $include_const

(optional) include constants list in final result

boolean $groupby_vers

(optional) give initial php version of function or constant

Return value

returns An array of php function/constant names history

Throws

throws no exceptions thrown

Since

since version 1.2.0 (2006-08-23)

Note

This function can not be called statically.

PHP_CompatInfo_Parser::getDirlist

PHP_CompatInfo_Parser::getDirlist() – Returns list of directory parsed

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

array PHP_CompatInfo_Parser::getDirlist ( mixed $dir , array $options )

Description

Returns list of directory parsed, depending of restrictive parser options.

Parameter
mixed $dir

The directory name

array $options

An array of parser options. See parseData() method.

Return value

returns array - list of directories that should be parsed

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Parser::getFilelist

PHP_CompatInfo_Parser::getFilelist() – Returns list of files parsed

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

array PHP_CompatInfo_Parser::getFilelist ( mixed $dir , array $options )

Description

Returns list of files parsed, depending of restrictive parser options.

Parameter
mixed $dir

The directory name where to look files

array $options

An array of parser options. See parseData() method.

Return value

returns array - list of files that should be parsed

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Parser::getIgnoredFiles

PHP_CompatInfo_Parser::getIgnoredFiles() – Returns list of files ignored

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

array PHP_CompatInfo_Parser::getIgnoredFiles ( )

Description

Returns list of files ignored while parsing directories

Return value

returns array or false on error

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Parser::parseData

PHP_CompatInfo_Parser::parseData() – Parse a data source

Synopsis
require_once 'PHP/CompatInfo/Parser.php';

array PHP_CompatInfo_Parser::parseData ( mixed $dataSource , array $options = array() )

Description

Parse a data source with auto detect ability. This data source, may be one of these follows: a directory, a file, a string (chunk of code), an array of multiple origin.

Each of five parsing functions support common and specifics options.

* Common options :

* parseArray, parseDir|parseFolder, specific options :

* parseArray specific options :

* parseDir|parseFolder specific options :

Parameter
mixed $dataSource

The data source (may be file, dir, string, or array)

array $options

An array of options. See above.

Return value

returns array or false on error

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

Example

see PHP_CompatInfo::parseData() example

Renderer Infrastructure

constructor PHP_CompatInfo_Renderer::PHP_CompatInfo_Renderer

constructor PHP_CompatInfo_Renderer::PHP_CompatInfo_Renderer() – Base Renderer Class constructor

Synopsis
require_once 'PHP/CompatInfo/Renderer.php';

void constructor PHP_CompatInfo_Renderer::PHP_CompatInfo_Renderer ( object &$parser , array $conf )

Description

Base Renderer Class constructor

Parameter
object &$parser

Instance of the parser (model of MVC pattern)

array $conf

A hash containing any additional configuration

Return value

returns instance of object PHP_CompatInfo_Renderer

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer::factory

PHP_CompatInfo_Renderer::factory() – Create required instance of the Output 'driver'

Synopsis
require_once 'PHP/CompatInfo/Renderer.php';

object PHP_CompatInfo_Renderer & PHP_CompatInfo_Renderer::factory ( object &$parser , string $type = 'array' , array $conf = array() )

Description

Creates a concrete instance of the renderer depending of $type

Parameter
object &$parser

A concrete instance of the parser

string $type

(optional) Type of instance required, case insensitive

array $conf

(optional) A hash containing any additional configuration information that a subclass might need.

Return value

returns A concrete PHP_CompatInfo_Renderer instance, or null on error.

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer::update

PHP_CompatInfo_Renderer::update() – Update the current view

Synopsis
require_once 'PHP/CompatInfo/Renderer.php';

void PHP_CompatInfo_Renderer::update ( object &$auditEvent )

Description

Interface to update the view with current information. Listen events produced by Event_Dispatcher and the PHP_CompatInfo_Parser

Parameter
object &$auditEvent

Instance of Event_Dispatcher

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer::startWaitProgress

PHP_CompatInfo_Renderer::startWaitProgress() – Initialize the wait process

Synopsis
require_once 'PHP/CompatInfo/Renderer.php';

void PHP_CompatInfo_Renderer::startWaitProgress ( integer $maxEntries )

Description

Initialize the wait process, with a simple message or a progress bar.

Parameter
integer $maxEntries

Number of source to parse

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer::stillWaitProgress

PHP_CompatInfo_Renderer::stillWaitProgress() – Update the wait message

Synopsis
require_once 'PHP/CompatInfo/Renderer.php';

void PHP_CompatInfo_Renderer::stillWaitProgress ( string $source , string $index )

Description

Update the wait message, or status of the progress bar

Parameter
string $source

Source (file, string) currently parsing

string $index

Position of the $source in the data source list to parse

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer::endWaitProgress

PHP_CompatInfo_Renderer::endWaitProgress() – Finish the wait process

Synopsis
require_once 'PHP/CompatInfo/Renderer.php';

void PHP_CompatInfo_Renderer::endWaitProgress ( )

Description

Finish the wait process, by erasing the progress bar

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer::isIncludable

PHP_CompatInfo_Renderer::isIncludable() – Checks if in the include path

Synopsis
require_once 'PHP/CompatInfo/Renderer.php';

boolean PHP_CompatInfo_Renderer::isIncludable ( string $file )

Description

Returns whether or not a file is in the include path

Parameter
string $file

Path to filename to check if includable

Return value

returns True if the file is in the include path, false otherwise

Throws

throws no exceptions thrown

Since

since version 1.7.0b4 (2008-04-03)

Note

This function can not be called statically.

Array Renderer

constructor PHP_CompatInfo_Renderer_Array::PHP_CompatInfo_Renderer_Array

constructor PHP_CompatInfo_Renderer_Array::PHP_CompatInfo_Renderer_Array() – Array Renderer Class constructor

Synopsis
require_once 'PHP/CompatInfo/Renderer/Array.php';

void constructor PHP_CompatInfo_Renderer_Array::PHP_CompatInfo_Renderer_Array ( object &$parser , array $conf )

Description

Array Renderer Class constructor

Parameter
object &$parser

Instance of the parser (model of MVC pattern)

array $conf

A hash containing any additional configuration

Return value

returns instance of object PHP_CompatInfo_Renderer_Array

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer_Array::display

PHP_CompatInfo_Renderer_Array::display() – Display final results

Synopsis
require_once 'PHP/CompatInfo/Renderer/Array.php';

void PHP_CompatInfo_Renderer_Array::display ( )

Description

Display final results, when data source parsing is over.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

Csv Renderer

constructor PHP_CompatInfo_Renderer_Csv::PHP_CompatInfo_Renderer_Csv

constructor PHP_CompatInfo_Renderer_Csv::PHP_CompatInfo_Renderer_Csv() – Csv Renderer Class constructor

Synopsis
require_once 'PHP/CompatInfo/Renderer/Csv.php';

void constructor PHP_CompatInfo_Renderer_Csv::PHP_CompatInfo_Renderer_Csv ( object &$parser , array $conf )

Description

Csv Renderer Class constructor

Parameter
object &$parser

Instance of the parser (model of MVC pattern)

array $conf

A hash containing any additional configuration

Return value

returns instance of object PHP_CompatInfo_Renderer_Csv

Throws

throws no exceptions thrown

Since

since version 1.8.0b4 (2008-06-18)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer_Csv::display

PHP_CompatInfo_Renderer_Csv::display() – Display final results

Synopsis
require_once 'PHP/CompatInfo/Renderer/Csv.php';

void PHP_CompatInfo_Renderer_Csv::display ( )

Description

Display final results, when data source parsing is over.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b4 (2008-06-18)

Note

This function can not be called statically.

Html Renderer

constructor PHP_CompatInfo_Renderer_Html::PHP_CompatInfo_Renderer_Html

constructor PHP_CompatInfo_Renderer_Html::PHP_CompatInfo_Renderer_Html() – Html Renderer Class constructor

Synopsis
require_once 'PHP/CompatInfo/Renderer/Html.php';

void constructor PHP_CompatInfo_Renderer_Html::PHP_CompatInfo_Renderer_Html ( object &$parser , array $conf )

Description

Html Renderer Class constructor

Parameter
object &$parser

Instance of the parser (model of MVC pattern)

array $conf

A hash containing any additional configuration

Return value

returns instance of object PHP_CompatInfo_Renderer_Html

Throws

throws no exceptions thrown

Since

since version 1.8.0b4 (2008-06-18)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer_Html::display

PHP_CompatInfo_Renderer_Html::display() – Display final results

Synopsis
require_once 'PHP/CompatInfo/Renderer/Html.php';

void PHP_CompatInfo_Renderer_Html::display ( )

Description

Display final results, when data source parsing is over.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b4 (2008-06-18)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer_Html::getStyleSheet

PHP_CompatInfo_Renderer_Html::getStyleSheet() – Returns the custom style sheet

Synopsis
require_once 'PHP/CompatInfo/Renderer/Html.php';

mixed PHP_CompatInfo_Renderer_Html::getStyleSheet ( int $destination = 1 , mixed $extra = null )

Description

Returns the custom style sheet to use for layout

Parameter
integer $destination

(optional) Destination of css content

mixed $extra

(optional) Additional data depending of destination

Return value

returns mixed

Throws

throws no exceptions thrown

Since

since version 1.8.0b4 (2008-06-18)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer_Html::setStyleSheet

PHP_CompatInfo_Renderer_Html::setStyleSheet() – Set a custom style sheet

Synopsis
require_once 'PHP/CompatInfo/Renderer/Html.php';

bool PHP_CompatInfo_Renderer_Html::setStyleSheet ( string $css = null )

Description

Set a custom style sheet to use your own styles

Parameter
string $css

(optional) File to read user-defined styles from

Return value

returns True if custom styles, false if default styles applied

Throws

throws no exceptions thrown

Since

since version 1.8.0b4 (2008-06-18)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer_Html::toHtml

PHP_CompatInfo_Renderer_Html::toHtml() – Returns HTML code

Synopsis
require_once 'PHP/CompatInfo/Renderer/Html.php';

string PHP_CompatInfo_Renderer_Html::toHtml ( object $obj )

Description

Returns HTML code of parsing result

Parameter
object $obj

instance of HTML_Table

Return value

returns string - html code

Throws

throws no exceptions thrown

Since

since version 1.8.0b4 (2008-06-18)

Note

This function can not be called statically.

Null Renderer

constructor PHP_CompatInfo_Renderer_Null::PHP_CompatInfo_Renderer_Null

constructor PHP_CompatInfo_Renderer_Null::PHP_CompatInfo_Renderer_Null() – Null Renderer Class constructor

Synopsis
require_once 'PHP/CompatInfo/Renderer/Null.php';

void constructor PHP_CompatInfo_Renderer_Null::PHP_CompatInfo_Renderer_Null ( object &$parser , array $conf )

Description

Null Renderer Class constructor

Parameter
object &$parser

Instance of the parser (model of MVC pattern)

array $conf

A hash containing any additional configuration

Return value

returns instance of object PHP_CompatInfo_Renderer_Null

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer_Null::display

PHP_CompatInfo_Renderer_Null::display() – Consumes output events

Synopsis
require_once 'PHP/CompatInfo/Renderer/Null.php';

void PHP_CompatInfo_Renderer_Null::display ( )

Description

Consumes all output events

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0RC1 (2008-07-01)

Note

This function can not be called statically.

Text Renderer

constructor PHP_CompatInfo_Renderer_Text::PHP_CompatInfo_Renderer_Text

constructor PHP_CompatInfo_Renderer_Text::PHP_CompatInfo_Renderer_Text() – Text Renderer Class constructor

Synopsis
require_once 'PHP/CompatInfo/Renderer/Text.php';

void constructor PHP_CompatInfo_Renderer_Text::PHP_CompatInfo_Renderer_Text ( object &$parser , array $conf )

Description

Text Renderer Class constructor

Parameter
object &$parser

Instance of the parser (model of MVC pattern)

array $conf

A hash containing any additional configuration

Return value

returns instance of object PHP_CompatInfo_Renderer_Text

Throws

throws no exceptions thrown

Since

since version 1.8.0b3 (2008-06-07)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer_Text::display

PHP_CompatInfo_Renderer_Text::display() – Display final results

Synopsis
require_once 'PHP/CompatInfo/Renderer/Text.php';

void PHP_CompatInfo_Renderer_Text::display ( )

Description

Display final results, when data source parsing is over.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b3 (2008-06-07)

Note

This function can not be called statically.

Xml Renderer

constructor PHP_CompatInfo_Renderer_Xml::PHP_CompatInfo_Renderer_Xml

constructor PHP_CompatInfo_Renderer_Xml::PHP_CompatInfo_Renderer_Xml() – Xml Renderer Class constructor

Synopsis
require_once 'PHP/CompatInfo/Renderer/Xml.php';

void constructor PHP_CompatInfo_Renderer_Xml::PHP_CompatInfo_Renderer_Xml ( object &$parser , array $conf )

Description

Xml Renderer Class constructor

Parameter
object &$parser

Instance of the parser (model of MVC pattern)

array $conf

A hash containing any additional configuration

Return value

returns instance of object PHP_CompatInfo_Renderer_Xml

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

PHP_CompatInfo_Renderer_Xml::display

PHP_CompatInfo_Renderer_Xml::display() – Display final results

Synopsis
require_once 'PHP/CompatInfo/Renderer/Xml.php';

void PHP_CompatInfo_Renderer_Xml::display ( )

Description

Display final results, when data source parsing is over.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 1.8.0b2 (2008-06-03)

Note

This function can not be called statically.

Command-Line version

constructor PHP_CompatInfo_Cli::PHP_CompatInfo_Cli

constructor PHP_CompatInfo_Cli::PHP_CompatInfo_Cli() – Command-Line Class constructor

Synopsis
require_once 'PHP/CompatInfo/Cli.php';

void constructor PHP_CompatInfo_Cli::PHP_CompatInfo_Cli ( )

Description

Command-Line Class constructor

Return value

returns instance of object PHP_CompatInfo_Cli

Throws

throws no exceptions thrown

Since

since version 0.8.0 (2004-04-22)

Note

This function can not be called statically.

PHP_CompatInfo_Cli::run

PHP_CompatInfo_Cli::run() – Run the CLI version

Synopsis
require_once 'PHP/CompatInfo/Cli.php';

void PHP_CompatInfo_Cli::run ( )

Description

Run the CLI version of PHP_CompatInfo

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.8.0 (2004-04-22)

Note

This function can not be called statically.