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.

  • Function dictionary CompatInfo/func_array.php provides a global array named $GLOBALS['_PHP_COMPATINFO_FUNCS'] what contains list of all functions implemented by all extensions.

  • Constant dictionary CompatInfo/const_array.php provides a global array named $GLOBALS['_PHP_COMPATINFO_CONST'] what contains list of all constants implemented by all extensions.

  • Class dictionary CompatInfo/class_array.php provides a global array named $GLOBALS['_PHP_COMPATINFO_CLASS'] what contains list of all classes implemented by all extensions.

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.

  • Function dictionary CompatInfo/libxml_func_array.php provides a global array named $GLOBALS['_PHP_COMPATINFO_FUNC_LIBXML'] what contains list of all functions implemented by Libxml extension.

  • Constant dictionary CompatInfo/libxml_const_array.php provides a global array named $GLOBALS['_PHP_COMPATINFO_CONST_LIBXML'] what contains list of all constants implemented by Libxml extension.

  • Class dictionary CompatInfo/libxml_class_array.php provides a global array named $GLOBALS['_PHP_COMPATINFO_CLASS_LIBXML'] what contains list of all classes implemented by Libxml extension.

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.

  • In CompatInfo directory where PCI was installed (standard is @php_dir@/PHP, where @php_dir@ identify the PEAR directory), edit:

    1. class_array.php add the resource PHP/CompatInfo/xsl_class_array.php and merge the global array $GLOBALS['_PHP_COMPATINFO_CLASS_XSL'] to main class dictionary named $GLOBALS['_PHP_COMPATINFO_CLASS']

    2. const_array.php add the resource PHP/CompatInfo/xsl_const_array.php and merge the global array $GLOBALS['_PHP_COMPATINFO_CONST_XSL'] to main constant dictionary named $GLOBALS['_PHP_COMPATINFO_CONST']

    3. func_array.php nothing to do because XSL extension does not provided any function.

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:

  • generate by default only all dictionaries corresponding to your platform.

    Default behavior is to overwrite default system PCI installation (results into @php_dir@/PHP/CompatInfo, where @php_dir@ identify the PEAR directory).

    If you don't want to overwrite default system PCI librairies, use the --output switch to write result in a directory accessible of your include_path

    Example1: pciconf --output @php_dir@/../includes/PHP/CompatInfo

    Example2: pciconf --output /etc/includes/PHP/CompatInfo

  • generate only a list of extension

    Use the --enable switch with a comma separated list of extension name (case sensitive)

    Example: pciconf --enable standard,date,gd,xsl

    Do not forget the standard extension, otherwise the result will be fake

  • generate all extensions of your platform without some of them

    Use the --disable switch with a comma separated list of extension name (case sensitive)

    Example: pciconf --disable xdebug

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.