Special extension package tags

Most of the tags for PECL-style PHP extension releases are identical to those for PEAR-style PHP script releases. There are a few extsrc/extbin-specific tags that all PECL developers must know about.

<providesextension>PDO</providesextension>

<name>PDO_windowsbin</name>
<channel>pecl.php.net</channel>
<!-- snip -->
<providesextension>PDO</providesextension>
<srcpackage>PDO</srcpackage>

<name>Foo_windowsbin</name>
<uri>http://www.example.com/Foo_windowsbin-1.5.0.tgz</uri>
<!-- snip -->
<providesextension>Foo</providesextension>
<srcuri>http://www.example.com/Foo-1.5.0.tgz</srcuri>

Quick introduction to channels

Channels are new in PEAR 1.4.0. Channels are a systemized way of differentiating between different download sources. One such download source is pear.php.net, another is pecl.php.net, and there are several third party channels slowly springing up around the net.

The <channel> tag should contain the full channel name, not any alias (don't use "pear", use "pear.php.net".

A good rule of thumb to use when determining what channel name to use is "where do I upload my releases to?" If the answer is pear.php.net, that is your package's channel. If the answer is pecl.php.net, then that is your channel.

If you aren't running a channel server and wish to serve your packages as well as allow other packages to remotely depend on your package, the new uri-based package distribution method is the best choice, see the <uri> tag documentation link below.

When to use <uri> instead of <channel>

If you do not have a channel server and wish to serve your packages so that others can depend on them, use <uri>. This should contain a static uri that links to a single package version's downloadable .tgz

If you do not need to allow external remote dependencies, then simply use the pear.php.net channel as your package's channel.

For instance, if you wish to serve package Foo version 1.1.0 from www.example.com, use the uri "http://www.example.com/Foo-1.1.0". Note that the uri must contain the full path MINUS THE EXTENSION. Provide both Foo-1.1.0.tgz and Foo-1.1.0.tar for users without gzip.

Documenting who develops a package

In package.xml 1.0, a developer was documented using the <maintainer> tag inside of a redundant <maintainers> container tag. This has been simplified in package.xml 2.0 both to slightly speed parsing and to make validation of the xml simpler. Now, the contents of the <role> tag has been extracted as 4 tags to describe the maintainers of a package.

In addition, a new internal tag <active> has been added, so that you can honor retired developers' work without having to remove them altogether from package.xml.

WARNING: tag order is important. List leads followed by developers followed by contributors and finally helpers.

Documenting release version and API version

In package.xml 1.0, the version was simply the version. package.xml 2.0 splits the concept of versioning into two components, release and api.

The release version is the same familiar versioning concept from package.xml 1.0. This version is validated very carefully by the packager.

The API version is informational only - the installer does not use it. It can be used for a package-time replacement by the installer. This can be very useful when implementing a reflective method such as getApiVersion(). In addition, the API version is very loosely validated, and only requires a version_compare()-compatible version number.

Documenting release stability and API stability

In package.xml 1.0, stability was known as "state" which is not the most accurate description. package.xml 2.0 introduces the term stability and like version splits the concept of stability into two components, release and api.

The release stability is the same familiar state from package.xml 1.0. It can be one of:

1. snapshot - a frozen picture of development at a particular moment

2. devel - a very new non-production release. Devel should be used for extremely new, practically untested code.

3. alpha - a new non-production release. Alpha should be used for new code that has an unstable API or untested code.

4. beta - a non-production release. Beta should be used for code that has a stable API and is nearing a fully stable release. Regresion tests and documentation should exist or soon follow to qualify as a beta release. Release candidates should use the beta stability.

5. stable - a production release. Stable releases must have a stable API, and must have regression tests and documentation.

The API stability is informational only - the installer does not use it.

Documenting release license

In package.xml 1.0, the license tag only contained the name of the license. In package.xml 2.0, there are two optional attributes, "uri" and "filesource". "uri" contains a uri that identifies the text of a license, such as "http://www.php.net/license" for the PHP License. "filesource" can be used to specify a LICENSE file within an actual package that contains the text of the license.

Documenting release contents

In package.xml 1.0, the contents tag was <filelist>. The purpose of the tag changed dramatically in package.xml 2.0, warranting a name change. Now, <filelist> can be found in the release section of the package.xml.

<contents> is used to describe the contents of a tarball. Nothing further. All files in the contents tag will be placed into the tarball regardless of whether they eventually get installed by the PEAR installer. This fact can be used to create a very versatile tarball, one that can be directly unzipped and work out of the box as well as be installed by the PEAR installer and work out of the box.

For most release types, contents contains a single <dir> tag that then either contains nested dir tags and/or <file> tags.

Documenting directories

The <dir> tag is identical to package.xml 1.0. Required attributes are name and optional attributes are baseinstalldir (the relative location where all files and subdirectories will be installed)

Note that all files must be contained in a single top-level <dir> tag. For simple packages, simply use <dir name="/"> as the directory name

Documenting files

The <file> tag is almost identical to package.xml 1.0. Required attributes are name and role. Optional attributes are baseinstalldir and md5sum. Optional attributes platform and install-as have been replaced by the release tags. Specifically, <install> is used to specify install-as, and the <ignore> tag can be used in conjunction with <installconditions> to exclude packages from being installed on particular platforms.

For those familiar with the platform attribute, the way to handle this example:

<file name="scripts/foo.bat" role="script" install-as="foo.bat" platform="windows">

is to in fact create two release sections. The file tag would then look like:

<file name="scripts/foo.bat" role="script">

and the release section would look like this:

<phprelease> <installconditions> <os>windows</os> </installconditions> <install name="scripts/foo.bat" as="foo.bat"/> </phprelease> <phprelease> <ignore name="scripts/foo.bat"/> </phprelease>

Note that the second <phprelease> tag could just as easily have had an <installconditions> tag containing <os>unix</os>, but this is unnecessary, as the second release will be processed on any system that is not a windows system.

Using tasks to customize file installation

Tasks provide a flexible and customizable way to manipulate file contents or to perform complex installation tasks (hence the name "tasks"). By default, PEAR comes with 4 tasks, but customized tasks can be added simply by adding a file into the PEAR/Tasks directory that follows the conventions of existing tasks. This page does not describe how to create a custom task, only how to use them in package.xml.

There are 3 basic tasks and 1 complex task distributed with PEAR. The basic tasks are "tasks:replace", "tasks:windowseol", and "tasks:unixeol". The complex task is "tasks:postinstallscript". "tasks:replace" is nearly identical to the old <replace> tag from package.xml 1.0, and does a text search-and-replace of a file's contents. "tasks:windowseol" and "tasks:unixeol" manipulate the line endings of a file to ensure that the correct line endings are in place for critical files like DOS .bat batch files and unix shell scripts. "tasks:postinstallscript" allows users to choose to run a script to perform further installation functions.

Working with <recommended> dependency versions and <compatible>

The <compatible> tag is designed to be used with a <package> dependency that contains a <recommended> version tag from package pear.example.com/Bar version 1.3.0 like so:

<package> <name>Foo</name> <channel>pear.example.com</channel> <min>1.0.0</min> <recommended>1.5.2</recommended> </package>

The above dependency can be translated into English as follows: "Use the package pear.example.com/Foo, but only versions 1.0.0 or newer. If pear.example.com/Foo is not installed, install version 1.5.2. If pear.example.com/Foo is installed and is not version 1.5.2, fail unless --force is specified, or pear.example.com/Foo is compatible with me."

That last clause "...or pear.example.com/Foo is compatible with me." is controlled by the <compatible> tag. If package Foo version 1.5.3's package.xml has a <compatible> like so:

<compatible> <name>Bar</name> <channel>pear.example.com</channel> <min>1.2.0</min> <max>1.3.0</max> <exclude>1.2.9</exclude> </compatible>

This will instruct the installer that pear.example.com/Foo version 1.5.3 is compatible with pear.example.com/Bar versions 1.2.0 to 1.3.0 inclusive, but is not compatible with 1.2.9.

It is very important to note that only existing versions that have been tested with the package should be mentioned in the <compatible> tag. Future versions of pear.example.com/Bar should simply upgrade the <recommended> tag.

<compatible> may contain three versioning tags. The required <min> and <max> are used to define the range of tested and compatible versions, and <exclude> is used to exclude any versions within the range. In the example above, 1.3.0 and 1.2.0 are the highest and lowest versions that may be excluded. There can be an unlimited number of <compatible> tags inside a package.xml.

Introduction to dependencies in package.xml 2.0

Dependencies are the most difficult aspect of programming. Using code written by other people can be a nightmare without simple ways to control bugs and API changes. Arguably, the handling of dependencies is PEAR's greatest strength, although there are many other nice features. Regardless of your personal opinion of the importance of dependencies, it is crucial to understand how to specify a dependency, and the different ways to ensure that your package is only used on systems that support it.

In package.xml 1.0, dependencies were relatively simple, but at the cost of usefulness. Specifying a dependency on a package for applications was actually dangerous. If you wished to limit an installed version of a package to a single version, it would mean preventing upgrade at any cost. package.xml 2.0 provides a simple way to enforce stricter dependency versioning without making upgrades onerous.

In package.xml 1.0, dependencies on PHP extensions like PECL extensions was near to a disaster. Extensions had to be present in the php.ini and loaded in memory in order to validate as being installed. This is often impossible, as a different php.ini is used for a production website versus the php.ini used for the pear installer. With package.xml 2.0, dependencies on a PECL-like extension is simple and straightforward, and only requires that the package be installed, and not that the extension be present in memory, although an older style extension dependency is also supported.

package.xml 1.0 supports two kinds of dependencies, required and optional. package.xml 2.0 also supports these two dependency types, but introduces a new kind of dependency concept: an optional dependency group. Dependency groups define a feature set. Instead of thinking "This package optionally depends on Net_FTP and optionally depends on Log" think "To remotely install packages, I need the remoteinstall feature, which needs Net_FTP and the Log package". This grouping allows defining sets of packages and extensions that comprise a feature and must be installed all at once for the feature to function properly.

package.xml 1.0 only supported php, package, and extension dependencies. package.xml 2.0 supports dependencies on php, package, extension, os, architecture, and PEAR installer. In addition, package.xml 2.0 supports depending on a static package located at a url, and depending on a package that provides an extension to PHP like PECL packages.

The PEAR installer dependency is not a dependency on the PEAR package, but a dependency on the currently running PEAR installer, and is more similar to a PHP dependency in that it requires the specified version to be running in memory. This is very useful for circumventing difficult bugs in the PEAR installer that render a package install useless.

<dep type="pkg" rel="has">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
</package>

<dep type="pkg" rel="ge" version="1.0.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <min>1.0.0</min>
</package>

<dep type="pkg" rel="gt" version="1.0.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <min>1.0.0</min>
 <exclude>1.0.0</exclude>
</package>

<dep type="pkg" rel="le" version="1.0.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <max>1.0.0</max>
</package>

<dep type="pkg" rel="ge" version="1.0.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <max>1.0.0</max>
 <exclude>1.0.0</exclude>
</package>

<dep type="pkg" rel="ge" version="1.0.0">Foo</dep>
<dep type="pkg" rel="le" version="1.9.0">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <min>1.0.0</min>
 <max>1.9.0</max>
</package>

<dep type="pkg" rel="not">Foo</dep>

<package>
 <name>Foo</name>
 <channel>pear.php.net</channel>
 <conflicts/>
</package>

Documenting custom file roles

Standard file roles provided by default with PEAR are:

• php

• data

• doc

• test

• script

• src

• ext

If your package chooses to use a role provided by a third party that implements some more advanced file installation handling, all you need to do is specify the role in the xml for the <file> tag that contains it like so:

<file role="foo"/>

However, if a user does not have the package installed that provides the custom role "foo", then the error message on installation will simply say "unknown role 'foo'", which is not very helpful.

The <usesrole> tag instead prompts the installer to tell the user "this package uses the custom role 'foo', install package pear.example.com/Foo to use"

<usesrole> <role>foo</role> <package>Foo</package> <channel>pear.example.com</channel> </usesrole>

Note that static URI packages (channel-less packages) are also supported:

<usesrole> <role>foo</role> <uri>http://pear.example.com/Foo-1.2.0</uri> </usesrole>

Documenting custom file tasks

Standard file tasks provided by default with PEAR are documented in this location.

If your package chooses to use a task provided by a third party, all you need to do is specify the task as part of the xml for the <file> tag that contains it like so:

<file role="php"> <tasks:foo/> </file>

However, if a user does not have the package installed that provides the custom task "foo", then the error message on installation will simply say "unknown task 'foo'", which is not very helpful.

The <usestask> tag instead prompts the installer to tell the user "this package uses the custom task 'foo', install package pear.example.com/Foo to use"

<usestask> <task>foo</task> <package>Foo</package> <channel>pear.example.com</channel> </usestask>

Note that static URI packages (channel-less packages) are also supported:

<usestask> <task>foo</task> <uri>http://pear.example.com/Foo-1.2.0</uri> </usesrole>

Documenting release type

In package.xml 1.0, there was one release type. package.xml 2.0 provides much finer control over the kind of release in order to provide three new release types: extension binary release, extension source release, and package bundle release.

All of the normal release tags (phprelease, extsrcrelease, extbinrelease) may contain two optional sections, <installconditions> and <filelist>. The purpose of these sections is to allow specification of different file install groups based on the target OS for installation, or other common install conditions.

To be clear: in package.xml, there was 1 <release> tag. package.xml 2.0 allows several adjacent release tags, each specifying a different install set. This actually simplifies complex installation filesets by separating the contents listing of the tarball from how the installer should manipulate this listing. Debugging installation file sets should be much simpler with this change.

The <filelist> tag can contain only two possible tags, <install> and <ignore>. install has two required attributes, "name" and "as". The install tag is used in the same manner as package.xml's install-as attribute for the <file>, to specify a new installation location for a file in the contents list. The ignore tag is used to completely ignore a file.

The <installconditions> tag can contain 4 tags whose format can be found in the <dependencies> section: <php>, <extension>, <os>, and <arch>. Each tag can appear exactly once except for the extension tag, which can appear limitless times.

The php tag is used to specify a php version or range of versions that an install set should be valid with.

The extension tag is used to specify extensions that must be present for an install set to be valid.

The os tag is used to specify an OS that must be present for an install set to be valid. Note that unix can be used to match all flavors, and linux can be used to match all linux-based OSes. Darwin should be used for Mac OS X, and * can be used to match all operating systems.

The arch tag is used to specify a uname string or portion of a uname string that must match in order for the install set to be valid.

Описание

Базовый класс PEAR предоставляет стандартную функциональность, которая может быть использована большинством классов PEAR. Обычно не требуется создавать объект этого класса, для этого используется наследование от него.

Главные особенности базового класса PEAR:

• "деструкторы" объектов, срабатывающие при завершении обработки запроса

• обработка ошибок

"деструкторы" PEAR

Если ваш класс ClassName наследует класс PEAR, то вы можете объявить метод _ClassName (имя класса с префиксом в виде подчеркивания), которые будет вызван по окончанию обработки запроса. Этот метод не является деструктором в том смысле, что вы можете "удалить" объект с его помощью, это метод объекта, который вызывается при завершении работы РНР. См. пример.

Обработка ошибок в PEAR

Базовый класс PEAR также предоставляет инструмент для обработки ошибок более сложных, чем возврат значений true/false или числовых кодов. Ошибка в PEAR - это объект, который является экземпляром класса PEAR_Error или класса, который наследует PEAR_Error.

Один из основных принципов обработки ошибок в PEAR гласит, что ошибки не должны автоматически приводить к выводу на экран пользователя, ошибки должны обрабатываться вообще без какого-либо вывода на экран, если это требуется. Это позволяет обрабатывать ошибки "вежливо", кроме того, это позволяет избежать нежелательного вывода тогда, когда вы используете не HTML, а, например, XML или WML.

Класс ошибок позволяет настроить себя так, что при возникновении ошибки (т.е. при создании экземпляра этого класса) могут выполняться различные действия. Например, вывод сообщения об ошибке, вывод сообщения и прекращение выполнения программы, вывод сообщения с помощью функции trigger_error(), вызов заранее назначенной функции или ничего из вышеперечисленного. Обычно эти параметры указываются в конструкторе PEAR_Error, но все эти параметры являются опциональными и вы можете использовать установки по умолчанию для ошибок, которые используются в классах, наследующих класс PEAR. См. примеры ошибок PEAR и документацию по PEAR_Error для более полной информации.

Примеры

Пример, приведенный ниже, показывает как использовать "деструкторы для бедных" PEAR для того, чтобы создать объект, содержимым которого является файл; объект позволяет добавлять данные в конец и записывает их при окончании обработки запроса:

Пример 27-1. Эмулируемые деструкторы PEAR require_once "PEAR.php"; class FileContainer extends PEAR { var $file = ''; var $contents = ''; var $modified = 0; function FileContainer($file) { $this->PEAR(); // вызов конструктора родительского класса $fp = fopen($file, "r"); if (!is_resource($fp)) { return; } while ($data = fread($fp, 2048)) { $this->contents .= $data; } fclose($fp); } function append($str) { $this->contents .= $str; $this->modified++; } // Деструктор зовется также, как и конструктор, но с приставкой в виде // подчеркивания function _FileContainer() { if ($this->modified) { $fp = fopen($this->file, "w"); if (!is_resource($fp)) { return; } fwrite($fp, $this->contents); fclose($fp); } } } $fileobj =& new FileContainer("testfile"); $fileobj->append("this ends up at the end of the file\n"); // При окончании обработки запроса, когда PHP прекращает свою работу, // вызывается деструктор объекта $fileobj и записывает файл на диск.

Следующие примеры иллюстрируют различные пути использования механизма обработки ошибок PEAR.

Пример 27-2. Пример обработки ошибок в PEAR (1) function mysockopen($host = "localhost", $port = 8090) { $fp = fsockopen($host, $port, $errno, $errstr); if (!is_resource($fp)) { return new PEAR_Error($errstr, $errno); } return $fp; } $sock = mysockopen(); if (PEAR::isError($sock)) { print "mysockopen error: ".$sock->getMessage()."<BR>\n" }

В примере используется враппер для fsockopen(), который при возникновении ошибки возвращает её код и текст в виде объекта PEAR_Error. Заметьте, что PEAR::isError() используется для того, чтобы определить является ли ошибкой возвращаемое значение.

PEAR_Error в этом примере работает в режиме, при котором ошибка просто возвращается, а её обработка ложится на плечи программиста. Это поведение является поведением по умолчанию.

В следующем примере мы покажем вам как использовать поведение по умолчанию:

Пример 27-3. PEAR error example (2) class TCP_Socket extends PEAR { var $sock; function TCP_Socket() { $this->PEAR(); } function connect($host, $port) { $sock = fsockopen($host, $port, $errno, $errstr); if (!is_resource($sock)) { return $this->raiseError($errstr, $errno); } } } $sock = new TCP_Socket; $sock->setErrorHandling(PEAR_ERROR_DIE); $sock->connect("localhost", 8090); print "still alive<BR>\n";

Здесь мы сначала меняем поведение по умолчанию на PEAR_ERROR_DIE, а потом, т.к. мы не указываем режим работы в raiseError() (это должно было бы быть 3-м параметром), raiseError() использует поведение по умолчанию и прекращает выполнение скрипта при завершении fsockopen() с ошибкой.

Использование глобальных переменных

Класс PEAR использует несколько глобальных переменных для установок по умолчанию, а список объектов используется для работы "деструкторов". Все глобальные переменные, которые использует класс PEAR носят имя с префиксом _PEAR_.

PEAR_ERROR_CALLBACK

Касается обработки ошибок PEAR.

См. PEAR_Error, setErrorHandling()

PEAR_ERROR_DIE

Касается обработки ошибок PEAR.

См. PEAR_Error, setErrorHandling()

PEAR_ERROR_PRINT

Касается обработки ошибок PEAR.

См. PEAR_Error, setErrorHandling()

PEAR_ERROR_RETURN

Касается обработки ошибок PEAR.

См. PEAR_Error, setErrorHandling()

PEAR_ERROR_TRIGGER

Касается обработки ошибок PEAR.

См. PEAR_Error, setErrorHandling()

Описание

Если вы хотите использовать функциональность деструкторов PEAR, то вам необходимо вызвать метод $this->PEAR() в конструкторе вашего класса.

Параметр

• string $errorClass - имя класса ошибок, который будет использоваться.

Заметка

Эта функция может быть вызвана статически.

Описание

Does nothing right now, but is included for forward compatibility, so subclass destructors should always call it.

Описание

Если ваш класс является статическим, то вам, вероятно, понадобятся статические атрибуты. Вы можете эмулировать их с помощью этого метода примерно так:

$myVar = &PEAR::getStaticProperty('myVar');

Использовать ссылку обязательно, иначе атрибут не будет статическим!

Параметр

• string $class - имя вашего класса, в котором вы вызываете getStaticProperty()

• string $var - имя статического атрибута

Возвращаемое значение

mixed - ссылку на атрибут. Если атрибут не был инициализирован, то ему автоматически будет присвоено значение NULL.

Пример

<?php

require_once 'PEAR.php';

class myClass {

function setValue( $set) 
{
 $foo = &PEAR::getStaticProperty('myClass', "foo");
 $foo = $set;
}

function view()
{
 print PEAR::getStaticProperty('myClass', "foo");
}

}

myClass::setValue('value = foo');
myClass::view();
?>

value = foo

Описание

Указанная функция вызывается перед тем, как интерпретатор заканчивает работу.

Параметр

• array $func - имя класса и его метод.

• array $var - аргументы вызываемой функции. Параметры передаются функции в том порядке, в котором они входят в массив.

Пример

<?php

require_once 'PEAR.php';

class myClass {

function myClass() 
{
 PEAR::registerShutdownFunc(array('myClass', 'shutdown'), 
                            array('param1', 'param2'));
}

function shutdown( $param1, $param2)
{
 // здесь делаем что-то
}

}

?>

Описание

isError() проверяет является ли переменная объектом PEAR_Error.

Параметр

• mixed $data - переменная, которая проверяется.

Возвращаемое значение

mixed - возвращает TRUE, если переменная является объектом PEAR_Error

Описание

raiseError()

Параметр

Возвращаемое значение

A PEAR_Error object is returned, unless PEAR_ERROR_DIE terminates execution or a PEAR_ERROR_EXCEPTION is never handled.

Описание

setErrorHandling() может быть вызвана статически и как метод объекта. При статическом вызове setErrorHandling() устанавливает поведение по умолчанию для всех объектов PEAR. При вызове метода объекта setErrorHandling() устанавливает поведение по умолчанию только для этого объекта.

Параметр

• integer $mode - имеет значение, равное одной из следующих констант:

  • PEAR_ERROR_RETURN если происходит ошибка, то возвращается объект PEAR_Error.

  • PEAR_ERROR_PRINT похожа на PEAR_ERROR_RETURN, но при этом выводится сообщение об ошибке.

  • PEAR_ERROR_TRIGGER похожа на PEAR_ERROR_RETURN, но при этом дополнительно вызывается функция trigger_error().

  • PEAR_ERROR_DIE - выполнение прерывается и выводится сообщение об ошибке.

  • PEAR_ERROR_CALLBACK - при возникновении ошибки вызывается указанная функция-обработчик. Функция должна принимать объект класса PEAR_Error в качестве параметра.

• mixed $options - значения опций зависят от параметра $mode

  • PEAR_ERROR_PRINT и PEAR_ERROR_DIE поддерживают опциональный параметр - строку для функции printf(), для форматирования вывода ошибки.

  • PEAR_ERROR_TRIGGER требует указания уровня ошибки: ( E_USER_NOTICE, E_USER_WARNING или E_USER_ERROR).

  • PEAR_ERROR_CALLBACK требует указания имени функции, которая будет вызвана.

Описание

Этот метод используется для того, чтобы указать какие ошибки вы ожидаете получить. Ожидаемые ошибки всегда возвращаются в режиме PEAR_ERROR_RETURN. Ожидаемые коды ошибок хранятся в стеке, а этот метод заносит в него новый элемент. Список ожидаемых ошибок используется до тех пор, пока они не извлечены из стека методом popExpect().

Параметр

• mixed $errorCode - ожидаемый код ошибки PEAR_Error или массив кодов. Если указано значение '*' - ожидается любая ошибка.

Возвращаемое значение

integer - размер стека кодов ошибок.

Заметка

Эта функция не должна вызываться статически.

См. также

popExpect()

Описание

Этот метод извлекает последний элемент из стэка кодов ожидаемых ошибок.

Возвращаемое значение

mixed - код ошибки, который был извлечен или массив кодов, которые были извлечены

Заметка

Эта функция не должна вызываться статически.

См. также

expectError()

Описание

Loads an extension by name

Параметр

Возвращаемое значение

boolean - returns TRUE, if extension could be loaded

Заметка

Эта функция может быть вызвана статически.

Пример

if(!PEAR::loadExtension("domxml")) {
 echo 'Could not load DomXML-Extension!';
 exit();
}

Описание

Добавляет пользовательскую информацию в объект ошибки.

Параметр

• string - пользовательская информация

Заметка

Эта функция не должна вызываться статически.

Описание

Возвращает имя функции, которая вызывается при возврате объекта PEAR_Error.

Возвращаемое значение

string - имя функции

Заметка

Эта функция не должна вызываться статически.

Описание

Возвращает код ошибки, который указан в объекте PEAR_Error.

Возвращаемое значение

integer - код ошибки

Заметка

Эта функция не должна вызываться статически.

Описание

Возвращает текст ошибки,который указан в объекте PEAR_Error.

Возвращаемое значение

string - текст ошибки

Заметка

Эта функция не должна вызываться статически.

Описание

Возвращает режим обработки ошибок, который учитывается при создании объекта PEAR_Error.

Возвращаемое значение

integer - режим обработки ошибок

Заметка

Эта функция не должна вызываться статически.

Описание

Возвращает отладочную информацию об ошибке

Возвращаемое значение

string - отладочная информация об ошибке

Заметка

Эта функция не должна вызываться статически.

Описание

Возвращает имя класса объекта ошибки.

Возвращаемое значение

string - имя класса

Заметка

Эта функция не должна вызываться статически.

Описание

Возвращает дополнительную информацию об ошибке

Возвращаемое значение

string - информация об ошибке

Заметка

Эта функция не должна вызываться статически.

Описание

Constructor

Параметр

• string $message - текст ошибки. Короткое описание возникшей проблемы.

• string $code - код ошибки.

• integer $mode - режим обработки ошибок.

• mixed $options - дополнительные опции режима обработки ошибок

• string $userinfo - строка с дополнительной инфорамацией об ошибке

Заметка

Эта функция может быть вызвана статически.

Описание

Возвращает строковое представление объекта.

Возвращаемое значение

string - строка с содержанием объекта ошибки

Заметка

Эта функция не должна вызываться статически.

Introduction

This class is available as part of the PEAR package. Features include:

• Fully unit-tested and documented

• blazingly fast - blows PEAR_Error out of the water

• Package-specific errors

• Error levels (notice/warning/error/exception)

• Error context data is saved separate from error message

• Error cascading - parent errors can be specified

• Dynamic error message generation allows generation of multiple and distinct error messages from the same error object

• Sophisticated callbacks are available for error message generation, error context generation, and error handling functionality, see Error Context Display, Custom Error Message Generation, and controlling error generation

PEAR_ErrorStack implements error raising and handling using a stack pattern. This has tremendous advantages over the PEAR_Error Implementation. PEAR_Error centralizes all error creation and handling in the constructor of the PEAR_Error object. Once an object has been created, all handling must have been completed, either through checking the return value of a method, or through a single global callback. In addition, it is nearly impossible to determine the source of an error, and the baggage of all of the PEAR base class's bulky, slow methods accompanies every error creation.

<?php // traditional PEAR_Error usage require_once 'PEAR.php'; class myobj { // there is no way to know where $err comes from function errorCallback($err) { $this->display($err->getMessage()); $this->log($err->getMessage()); } function log($msg) { error_log($msg, 3, 'somefile.log') } function display($msg) { echo $msg . '<br />'; } } $myobj = new myobj; // using a callback PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, array(&$myobj, 'errorCallback')); $ret = SomePackage::doSomething(); if (PEAR::isError($ret)) { // do some handling - this error is also displayed and logged } PEAR::pushErrorHandling(PEAR_ERROR_RETURN); $ret = SomePackage::doSomething(); if (PEAR::isError($ret)) { // do some handling - this error is not displayed or logged } PEAR::popErrorHandling(); ?>

The PEAR_ErrorStack class has built in knowledge of the Log package, can easily differentiate and even automatically re-package errors with little to no difficulty.

<?php // PEAR_ErrorStack error handling require_once 'PEAR/ErrorStack.php'; require_once 'Log.php'; define('MYPACKAGE_ERROR_DBERROR', 1); class myobj { var $_stack; function myobj() { $this->_stack = &PEAR_ErrorStack::singleton('MyPackage'); } function errorCallback($err) { switch($err['package']){ case 'MyPackage': // tell the error stack to log the error only // it will not be pushed onto the stack return PEAR_ERRORSTACK_LOG; break; case 'InternalDbPackage': // re-package these errors as a mypackage error fit // for enduser consumption $this->_stack->push(MYPACKAGE_ERROR_DBERROR, 'error', array('dbmessage' => $err['message'], 'dbcode' => $err['code'], 'We are having Connection problems, please' . 'try again in a few moments'), '', $err); // include the error as re-packaged // tell the internal DB error stack to ignore this error, // as if it never happened return PEAR_ERRORSTACK_IGNORE; break; } // switch } } $myobj = &new myobj; // separate error stacks for my package, and the internal DB package $dbstack = &PEAR_ErrorStack::singleton('InternalDbPackage'); $mystack = &PEAR_ErrorStack::singleton('MyPackage'); // set up a file log using PEAR::Log $log = &Log::Factory('file', 'somefile.log', 'MyPackage error log'); $mystack->setLogger($log); // set up a default log to use for all error stacks PEAR_ErrorStack::setDefaultLogger($log); // any errors returned by MyPackage are logged $ret = SomePackage::doSomething(); // Note that $ret need not be checked for any error condition - errors are // totally separate from code if ($dbstack->hasErrors()) { var_dump($dbstack->getErrors(); } // sets a default callback for all errors PEAR_ErrorStack::setDefaultCallback(array(&$myobj, 'errorCallback')); // any db errors are transparently repackaged as // user-friendly MyPackage errors now $ret = SomePackage::doSomething(); ?>

Why write a new error-handling routine when PEAR_Error already exists? There are several problems with PEAR_Error. Although an error message is present in an error class, processing this error message automatically is excessively difficult for computers. In addition, the error message cannot easily be translated once it has been placed into the PEAR_Error. There is also no standard facility for storing error-related data in the error class. On top of error message-related issues, there is no way to automatically determine which package a PEAR_Error object comes from, or the severity of an error. Fatal errors look exactly the same as non-fatal errors.

The largest flaw with PEAR_Error object is the single-error type design. Every PEAR_Error object is just a PEAR_Error object. There is no differentiating between the severity of an error, or its origin. The only way to determine the severity is to use PEAR_ERROR_TRIGGER and E_USER_NOTICE/E_USER_WARNING/E_USER_ERROR constants from php's trigger_error. But using this functionality does not justify 900 lines of code, simply because trigger_error() is built into PHP itself!

Now, to start using your newly created error objects, change all of your PEAR::raiseError() or PEAR::throwError() calls from this...

<?php require_once 'PEAR.php'; // old way: $error_specific_info = 'bad'; $e = PEAR::raiseError("error message - very " . $error_specific_info . " way to do things", MYPACKAGE_ERROR_FOO); // another old way: $e = PEAR::throwError("error message - very " . $error_specific_info . " way to do things", MYPACKAGE_ERROR_FOO); ?>

...to something like this:

<?php require_once 'PEAR/ErrorStack.php'; // new way // version 1: stack instance access $stack = &PEAR_ErrorStack::singleton('MyPackage'); $stack->push(MYPACKAGE_ERROR_DBERROR, 'error', array('query' => $query, 'dsn' => $dsn), 'Critical Database Error: Contact Administrator immediately'); // version 2: static singleton access (slightly slower) PEAR_ErrorStack::staticPush('MyPackage', MYPACKAGE_ERROR_DBERROR, 'error', array('query' => $query, 'dsn' => $dsn), 'Critical Database Error: Contact Administrator immediately'); ?>

For basic use, this is all that is needed to use the PEAR_ErrorStack package in place of PEAR_Error.

Advanced Features

Backwards compatibility with PEAR_Error, Forward compatibility with PHP 5 Exception and PEAR_Exception

PEAR_ErrorStack can also be programmed to automatically raise a PEAR_Error using PEAR::raiseError(), simply pass in true to the PEAR_Error compatibility like so:

<?php require_once 'PEAR/ErrorStack.php'; $stack = &PEAR_ErrorStack::singleton('mypackage', false, false, true); ?>

PEAR_ErrorStack can coordinate with the new PEAR_Exception class to convert into an exception with this code: You can set the exception class name that will be returned using the following code:

<?php require_once 'PEAR/ErrorStack.php'; require_once 'PEAR/Exception.php'; $stack = &PEAR_ErrorStack::singleton('mypackage'); $stack->push(1, 'test error'); throw new PEAR_Exception('did not work', $stack->pop()); ?>

Backwards Compatibility Warning

Описание

Creates a new private PEAR_ErrorStack. To access a universal stack, use PEAR_ErrorStack::singleton()

Параметр

Throws

throws no exceptions thrown

Заметка

Эта функция не должна вызываться статически.

Описание

This method may also be called by a custom error message generator to fill in template values from the params array, simply set the third parameter to the error message template string to use

The special variable %__msg% is reserved: use it only to specify where a message passed in by the user should be placed in the template, like so:

Error message: %msg% - internal error

If the message passed like so:

<?php $stack->push(ERROR_CODE, 'error', array(), 'server error 500'); ?>

The returned error message will be "Error message: server error 500 - internal error"

Параметр

Throws

throws no exceptions thrown

Заметка

Эта функция должна вызываться статически.

Описание

Standard Error Message Template generator from error code

Параметр

Throws

throws no exceptions thrown

Заметка

Эта функция не должна вызываться статически.

Описание

Retrieve all errors since last purge, or filter all errors and only return errors of a particular error level, leaving the rest on the stack.

Параметр

Throws

throws no exceptions thrown

Заметка

Эта функция не должна вызываться статически.

Описание

This function uses a backtrace generated from debug_backtrace and so will not work at all in PHP < 4.3.0. The frame should reference the frame that contains the source of the error.

Параметр

Возвращаемое значение

returns either array('file' => file, 'line' => line, 'function' => function name, 'class' => class name) or if this doesn't work, then false

Throws

throws no exceptions thrown

Заметка

Эта функция должна вызываться статически.

Описание

This method returns the current callback that can be used to generate error messages

Возвращаемое значение

returns Callback function/method or false if none

Throws

throws no exceptions thrown

Заметка

Эта функция не должна вызываться статически.

Описание

Determine whether there are any errors on the stack

Параметр

Throws

throws no exceptions thrown

Заметка

Эта функция не должна вызываться статически.

Описание

Pop an error off of the error stack

Throws

throws no exceptions thrown

Заметка

since 0.4alpha it is no longer possible to specify a specific error level to return - the last error pushed will be returned instead.

Заметка

Эта функция не должна вызываться статически.

Описание

Remove a callback from the error callback stack

Throws

throws no exceptions thrown

См. также

see PEAR_ErrorStack::pushCallback()

Заметка

Эта функция не должна вызываться статически.

Backwards Compatibility Warning

Описание

If the message generator exists, it is called with 2 parameters.

• the current Error Stack object

• an array that is in the same format as an error. Available indices are 'code', 'package', 'time', 'params', 'level', and 'context'

Параметр

Возвращаемое значение

returns if compatibility mode is on, a PEAR_Error is also thrown. If the class Exception exists, then one is returned to allow code like:

<?php 1 throw ($stack->push(MY_ERROR_CODE, 'error', array('username' => 'grob'))); ?>

The errorData property of the exception class will be set to the array that would normally be returned. If a PEAR_Error is returned, the userinfo property is set to the array

Otherwise, an array is returned in this format:

<?php 1 array( 2 'code' => $code, 3 'params' => $params, 4 'package' => $this->_package, 5 'level' => $level, 6 'time' => time(), 7 'context' => $context, 8 'message' => $msg, 9 //['repackage' => $err] repackaged error array 10 ); ?>

Throws

No exceptions thrown.

Заметка

Эта функция не должна вызываться статически.

Описание

The return value must be one of the PEAR_ERRORSTACK_* constants.

This functionality can be used to emulate PEAR's pushErrorHandling, and the PEAR_ERROR_CALLBACK mode, without affecting the integrity of the error stack or logging

Параметр

Throws

throws no exceptions thrown

См. также

see PEAR_ErrorStack::popCallback()

see PEAR_ERRORSTACK_PUSHANDLOG, PEAR_ERRORSTACK_PUSH, PEAR_ERRORSTACK_LOG

Заметка

Эта функция не должна вызываться статически.

Описание

See PEAR::raiseError()

Throws

No exceptions thrown.

Заметка

Эта функция может быть вызвана статически.

Описание

This method sets the callback that can be used to generate context information for an error. Passing in NULL will disable context generation and remove the expensive call to debug_backtrace()

Параметр

Throws

No exceptions thrown.

Заметка

Эта функция не должна вызываться статически.

Описание

This method sets the callback that can be used to generate error messages for a singleton

Параметр

Throws

No exceptions thrown.

Заметка

Эта функция должна вызываться статически.

Описание

Set up a PEAR::Log object for all error stacks that don't have one

Параметр